In this tutorial, you will learn how Laravel AI agents work, how to create custom tools, how to handle failures, how human approval fits into agent workflows, and how to test your implementation.
What Is New in Laravel AI SDK 1.4?
Laravel AI SDK provides a Laravel-native interface for working with AI providers, agents, tools, conversations, embeddings, and other AI capabilities.
The 1.4 release focuses on improving the reliability of agent execution and developer testing.
| Improvement | Developer benefit |
|---|---|
| Tool failure recovery | Tool exceptions can be returned to the model as tool results, allowing the run to continue. |
| Agent fake improvements | Tests can resume agents with paused tool approvals. |
| Raw HTTP responses | More response types expose the underlying HTTP response. |
| OpenAI billing errors | Insufficient credits use a more specific exception. |
| Provider stream errors | Provider stream errors use a consistent error event name. |
| Conversation events | Conversation title generation fires the usual agent events. |
The important distinction is that failure recovery does not guarantee that every failed operation will succeed. It gives the model an opportunity to interpret a tool failure and decide what to do next.
1. Install Laravel AI SDK
Install the Laravel AI SDK using Composer:
Configure the AI provider credentials according to the provider you intend to use. Keep API keys in environment variables or a secrets manager. Never expose provider credentials in frontend JavaScript or commit them to Git.
For the complete provider configuration and supported capabilities, consult the official Laravel AI SDK documentation.
2. Create Your First AI Agent
Laravel AI SDK uses dedicated PHP classes to define agents. An agent can contain instructions, conversation context, tools, and structured output configuration.
Generate an agent:
A basic agent can be prompted through its PHP class:
The AI model can answer using its instructions and any tools made available by the agent. Tools are especially useful when an AI application needs to interact with databases, APIs, or business services.
3. Understand AI Agent Tool Calling
Tool calling allows an AI model to request a specific operation from your application. Instead of directly accessing your database or external services, the model requests a tool and Laravel executes the corresponding PHP code.
A typical workflow looks like this:
- The user sends a request.
- The agent analyzes the request.
- The model decides whether a tool is required.
- Laravel executes the selected tool.
- The tool result is returned to the model.
- The agent generates its response.
This architecture separates AI reasoning from application permissions and business logic.
4. Build a Custom Laravel AI Tool
Generate a tool using Artisan:
Laravel places generated tools in the application's app/Ai/Tools directory. A tool implements Laravel's Tool contract and defines its description, input schema, and handle method.
For example, a support agent might need a tool that retrieves an order status. Keep authorization and ownership checks inside the application logic, not inside the AI prompt alone.
Use the generated tool skeleton as the source of truth for the exact method signatures in your installed SDK version. The following is the conceptual tool workflow:
Important: This is an illustrative skeleton, not a complete executable tool. Implement the schema and handle method using the signatures generated by your installed Laravel AI SDK version.
5. What Happens When an AI Tool Fails?
Consider an AI support agent that uses an external order management API.
Imagine the API is temporarily unavailable. In an older failure-handling workflow, an exception from a tool could interrupt the agent run. With Laravel AI SDK 1.4, tool exceptions can be delivered back to the model as tool results, allowing the agent run to continue.
The model can then explain that the service is unavailable, provide an alternative answer, or attempt another permitted action.
Example failure scenario
The key benefit is that the model receives information about the failed operation instead of the entire workflow necessarily ending at that point.
6. Build Reliable Failure Handling
Returning a tool failure to the model is useful, but production applications still need proper error handling.
Separate expected business failures from infrastructure failures:
- Order not found: return a safe business-level result.
- Permission denied: reject the operation.
- API timeout: record the failure and apply appropriate retry policies.
- Rate limit: respect the provider's retry guidance.
- Invalid input: validate before performing the operation.
Do not expose database credentials, access tokens, internal hostnames, stack traces, or sensitive customer information in tool error messages.
Also avoid blindly retrying every failed operation. For payment requests, email delivery, order creation, and other side effects, use idempotency keys and transaction-aware recovery.
7. Human Approval for Sensitive AI Tools
AI agents should not automatically perform every operation they can request.
For sensitive actions such as deleting files, issuing refunds, transferring funds, or sending external notifications, use human approval.
Laravel AI SDK provides the Approvable contract and InteractsWithApprovals trait for tools requiring approval.
Conceptually, the process is:
- The agent requests a sensitive tool operation.
- The application pauses the agent.
- The application displays the requested operation and its arguments.
- An authorized user approves, rejects, or edits the request.
- The application resumes the conversation with the decision.
Always authorize access to the conversation before resuming a paused agent. A tool approval mechanism does not replace application-level authorization.
8. Test AI Agents and Tool Failures
AI features should be tested without relying on live model responses for every test.
Laravel AI SDK supports faking agent responses. The SDK 1.4 improvements also make it possible to test agents that resume paused tool approvals.
This example tests the agent's response using a fake. It does not simulate an actual external tool exception. For tool recovery, add separate tests that exercise your tool's failure behavior and verify the resulting agent workflow.
9. Production Architecture for Laravel AI Agents
For a production application, keep AI orchestration separate from business operations.
| Component | Responsibility |
|---|---|
| AI Agent | Instructions and model interaction |
| Tool classes | Controlled access to application operations |
| Service classes | Business rules and reusable logic |
| Database | Persistent application and conversation data |
| Queue workers | Long-running or asynchronous operations |
| Approval workflow | Human authorization for sensitive actions |
| Monitoring | Errors, latency, token usage and execution history |
For long-running AI tasks, use Laravel queues where appropriate. Configure worker timeouts, memory limits, retry policies and failed-job handling carefully. Do not treat an AI agent's ability to continue after a tool exception as a replacement for queue-level reliability.
10. Laravel AI SDK 1.4 Best Practices
- Give each tool one clear responsibility.
- Validate all model-provided tool arguments.
- Check user permissions before accessing business data.
- Keep secrets outside prompts and tool results.
- Require approval for sensitive actions.
- Use idempotency for operations with external side effects.
- Log tool execution metadata without logging private data.
- Set appropriate timeouts and retry limits.
- Test successful and failed execution paths.
- Monitor token consumption and provider errors.
Laravel AI SDK 1.4 vs Earlier Versions
| Area | Earlier workflow | Version 1.4 improvement |
|---|---|---|
| Tool exceptions | Could interrupt the agent run | Can be returned as tool results |
| Approval testing | Less convenient for resumed fake agents | Fakes can resume paused approvals |
| Response inspection | Fewer response types exposed raw HTTP data | Five additional response types expose it |
| OpenAI billing errors | Could be reported as rate-limit errors | Uses InsufficientCreditsException |
Frequently Asked Questions
What is Laravel AI SDK 1.4?
Laravel AI SDK 1.4 is an update to Laravel's first-party AI SDK that improves agent tool failure handling, approval testing, response inspection and provider error reporting.
Can Laravel AI agents recover from tool failures?
Yes. In version 1.4, tool exceptions can be returned to the model as tool results, allowing the agent run to continue. This does not guarantee that the underlying operation will succeed.
How do I create an AI agent in Laravel?
Install the Laravel AI SDK and use php artisan make:agent to generate an agent class. Configure its instructions and tools, then invoke it with the prompt method.
Can Laravel AI agents call external APIs?
Yes. You can create custom tools that communicate with external APIs and expose controlled functionality to an agent.
Does Laravel AI SDK support human approval?
Yes. Tools can implement the Approvable contract and InteractsWithApprovals trait so sensitive actions can pause for a user decision.
Can I test Laravel AI agents without calling a real AI provider?
Yes. Agent fakes allow you to provide predetermined or dynamically generated test responses. You should also test tool execution and failure paths separately.
Conclusion
Laravel AI SDK 1.4 makes agent workflows more resilient by allowing tool failures to be communicated back to the model instead of always terminating the run.
For developers building AI-powered SaaS products, support automation, RAG applications, and business assistants, this is an important improvement. Combine failure recovery with authorization, human approvals, idempotency, monitoring, and automated tests to build reliable production AI systems.
Are you building AI agents with Laravel? Explore the SDK, experiment with custom tools, and share your implementation challenges with the developer community.
Official Resources
Version note: Examples target Laravel 13 and the Laravel AI SDK 1.x API. Verify generated tool method signatures against the installed SDK version before using illustrative snippets in production.
