Laravel Ai Assistant Laravel Package

Getting Started

This release is a quality-of-life upgrade for the Responses API adapter: you can now pass Chat Completions-style messages payloads and let the package transform them into Responses API input blocks automatically. It is backwards compatible, but it is still a beta, so pin the version in composer.json before relying on it.

Minimal setup:

1. Install and configure the package as usual (Composer, published config, API key/environment variables).
2. Start with the Responses API adapter and InputBuilder. The first thing to inspect is how your adapter maps a request payload into input — especially the new messages → input conversion path.
3. First use case: send a simple chat-style payload:

$response = $client->responses()->create([
    'model' => '...',
    'messages' => [
        ['role' => 'user', 'content' => 'Summarize this ticket.'],
    ],
]);

With 3.0.31-beta, the adapter will convert that messages array into a single user message with an input_text block, remove messages, and send input to the Responses API.

Where to look first:

• The Responses API adapter's request transformation logic.
• InputBuilder::message() — it now sets both input and the legacy message key.
• Any tests or fixtures covering chat-style payload conversion, image blocks, and file_id handling.

Implementation Patterns

Chat-style passthrough for migrations. If you are moving existing Chat Completions code to the Responses API, keep your existing messages arrays initially. The adapter converts strings and type: text|input_text content into input_text blocks, and image content into input_image blocks. This is the lowest-friction migration path.

Prefer explicit input for new code. Use InputBuilder or construct input blocks directly. Explicit input is preserved and takes precedence; the adapter only converts messages when input is not provided. This keeps your intent clear and avoids relying on implicit normalization.

Multimodal requests. Image content is normalized from either a string or { url: ... } into input_image with image_url. If you already use type: input_image, the adapter supports both image_url and file_id. Use file_id for previously uploaded files, especially large images, rather than re-sending URLs or base64 payloads.

Builder usage. InputBuilder::message() now sets input to a single user message with an input_text block while retaining the original message key for backward compatibility. Use the builder when you want a consistent, Response-API-native payload but still need compatibility with older code paths or tests that inspect message.

Integration tips.

• Keep request construction in a dedicated service/action class rather than scattering payload shapes across controllers.
• If you support multiple providers or endpoints, normalize at your application boundary and let the adapter handle the final conversion to the Responses API.
• In tests, assert against the transformed input payload rather than only the raw messages input, since messages is removed after conversion.
• Use Laravel's HTTP client fakes/events or the package's testing helpers (if provided) to inspect the outgoing request body.

Gotchas and Tips

• Beta status. Treat 3.0.31-beta as unstable API surface. Pin the exact version and review future beta notes for changes to normalization behavior.
• messages is removed after conversion. Do not rely on the original messages key being present in the outgoing payload or in request logs after the adapter runs. If you need an audit trail, capture the input before transformation or log the resulting input.
• Explicit input wins. If both input and messages are present, the adapter preserves input and removes messages. This is useful for overrides, but it can also hide a stale messages array — check your payloads when debugging unexpected behavior.
• Duplicate keys from InputBuilder::message(). The builder preserves the message key while also setting input. That is intentional for backward compatibility, but strict payload assertions or serializers may see both. Assert on input for Responses API behavior and on message only for legacy compatibility.
• Image normalization is shape-sensitive. A string or { url: ... } under type: image_url becomes input_image with image_url. If you already send input_image, make sure you use either image_url or file_id as expected. Malformed nested arrays are the most likely source of conversion surprises.
• Debugging conversion issues. Log or dump the payload immediately before the HTTP request. If the transformed input looks wrong, check whether you accidentally supplied input alongside messages, or whether your content blocks use unsupported type values.
• Extension points. If the built-in normalization does not cover a content type you need, prefer a small application-level transformer that produces explicit input blocks rather than patching the adapter. This keeps you compatible with future package releases and avoids depending on beta internals.