Laravel 13 AI SDK: Build a Useful First Agent Without Losing Control

An AI feature becomes useful when it performs one well-defined job inside an application. Consider a support inbox: a new ticket arrives, somebody reads it, chooses a priority, assigns a team, and writes a short summary. The classification step is a good candidate for an AI agent. The database update, access checks, and final assignment still belong to your application.

Laravel 13 introduced a first-party AI SDK for agents, structured output, embeddings, and other AI tasks. Laravel 13 requires PHP 8.3 or newer. This guide starts with a small ticket-triage agent and shows how to keep its output reviewable. See the Laravel 13 release notes and AI SDK documentation for the current API.

The smallest useful workflow

Suppose a customer writes: “I was charged twice and cannot download the book I bought.” Your application needs three fields: an issue category, a priority, and a brief reason. A free-form paragraph is awkward to validate and difficult to route. Structured output gives the application predictable fields while letting the model interpret the customer’s words.

Start by installing and configuring the SDK according to the current installation instructions. Add the provider credentials to your server environment, never to frontend code or a public repository. Then create an agent:

php artisan make:agent TicketTriage --structured

The generator creates the class and a place for its output schema. Configure it to return fields such as category, priority, and reason. Restrict category and priority to a short list of allowed values. Give the agent instructions that explicitly say it must classify only the supplied ticket and should mark unclear cases for human review.

The exact generated method signatures can evolve with SDK versions, so use the generated class and current documentation as the source of truth. The important contract is stable: ticket text goes in; validated classification comes out.

Keep decisions in application code

Imagine the model proposes priority = urgent. That is a recommendation, not permission to change a customer's account or issue a refund. Validate the structured fields, then apply your own rules:

1. Confirm the authenticated user may access the ticket.
2. Check whether the category and priority are allowed values.
3. Route sensitive requests, such as payments or account recovery, to a human queue.
4. Save both the recommendation and the final human decision so you can review disagreements.

This separation makes bugs easier to investigate. If the ticket landed in the wrong queue, you can tell whether the model misclassified it or your routing rule was wrong.

Add tools only when the job needs them

Laravel agents can be given tools, but a first triage agent may not need any. If you later let it fetch an order, expose a narrowly scoped, read-only tool that returns the minimum necessary order facts. The server must enforce the current user's permissions inside the tool; an instruction such as “only read this user's orders” is not an authorization control.

Do not hand the agent a generic SQL executor, unrestricted HTTP client, or refund action just because those capabilities are available. When a workflow needs a consequential action, make the agent propose it and require ordinary application validation and, where appropriate, a human approval.

A production checklist that catches real failures

Test ambiguity. Try short tickets, multilingual tickets, sarcasm, missing order numbers, and messages containing two separate problems. Define what “needs review” looks like.

Measure quality. Assemble a small, consent-appropriate set of historical examples with human labels. Track category agreement and false urgent decisions before and after changing a prompt or model. Do not treat a convincing demo as an accuracy measurement.

Protect private data. Remove unnecessary personal details before sending a ticket to a provider. Set retention and logging rules deliberately, and ensure your team understands where request content goes.

Handle failure. Set a timeout, catch provider errors, and fall back to a manual triage queue. A failed AI request must not cause the ticket itself to disappear.

Watch cost and latency. Record model, token usage where available, response time, and fallback rate. A queue may be suitable for classification that does not have to block the customer-facing request.

When to use embeddings instead

An agent classifies or generates an answer. Embeddings help locate similar content. If the support agent must answer “Where is the refund policy?”, first retrieve the relevant policy passages and pass them into the prompt. Laravel 13 documents embedding generation and vector queries. A companion guide on PostgreSQL hybrid search explains why keyword and semantic retrieval work well together.

The takeaway

Build your first agent around a narrow task, a structured contract, and a measurable fallback. The SDK simplifies provider integration. Your Laravel code remains responsible for permissions, validation, persistence, and the consequences of every action.

Sources

• Laravel 13 release notes
• Laravel AI SDK documentation