From e5cde6e5802078c6419652e105cb3811e997366d Mon Sep 17 00:00:00 2001 From: Fabian Schindler Date: Tue, 23 Jun 2026 16:36:10 +0200 Subject: [PATCH 1/2] docs(laravel): Add AI monitoring guide Document Laravel AI agent monitoring support, including setup, verification, conversation tracking, and feature flags. Link the new guide from AI Monitoring and Conversations docs so users can discover the integration. --- docs/ai/monitoring/agents/getting-started.mdx | 1 + docs/ai/monitoring/conversations/index.mdx | 1 + .../laravel/integrations/laravel-ai.mdx | 232 ++++++++++++++++++ .../automatic-instrumentation.mdx | 1 + 4 files changed, 235 insertions(+) create mode 100644 docs/platforms/php/guides/laravel/integrations/laravel-ai.mdx diff --git a/docs/ai/monitoring/agents/getting-started.mdx b/docs/ai/monitoring/agents/getting-started.mdx index 261ff783743c0a..8b4a80d09ac0ec 100644 --- a/docs/ai/monitoring/agents/getting-started.mdx +++ b/docs/ai/monitoring/agents/getting-started.mdx @@ -25,6 +25,7 @@ To use [Conversations](/ai/monitoring/conversations/), set a conversation ID for To start sending AI agent data to Sentry, make sure you've created a Sentry project for your AI-enabled repository and follow one of the guides below: - [Python](/platforms/python/tracing/instrumentation/custom-instrumentation/ai-agents-module) +- [Laravel](/platforms/php/guides/laravel/integrations/laravel-ai/) - [Node.js](/platforms/javascript/guides/node/ai-agent-monitoring/) - [Browser (JavaScript)](/platforms/javascript/ai-agent-monitoring-browser/) - [React](/platforms/javascript/guides/react/ai-agent-monitoring-browser/) diff --git a/docs/ai/monitoring/conversations/index.mdx b/docs/ai/monitoring/conversations/index.mdx index c477b1c547a6fd..15927b719bd531 100644 --- a/docs/ai/monitoring/conversations/index.mdx +++ b/docs/ai/monitoring/conversations/index.mdx @@ -40,6 +40,7 @@ Some SDK integrations (such as OpenAI Agents SDK for Python and OpenAI SDK for N - [JavaScript/Node](/platforms/javascript/guides/node/ai-agent-monitoring/#tracking-conversations) - [Python](/platforms/python/tracing/instrumentation/custom-instrumentation/ai-agents-module/#tracking-conversations) +- [Laravel](/platforms/php/guides/laravel/integrations/laravel-ai/#conversations) ### Conversations and Traces diff --git a/docs/platforms/php/guides/laravel/integrations/laravel-ai.mdx b/docs/platforms/php/guides/laravel/integrations/laravel-ai.mdx new file mode 100644 index 00000000000000..f8014c09dc8fdc --- /dev/null +++ b/docs/platforms/php/guides/laravel/integrations/laravel-ai.mdx @@ -0,0 +1,232 @@ +--- +title: Laravel AI +description: "Learn about using Sentry for Laravel AI agent monitoring." +--- + + + +Laravel AI support is in beta. Test locally before using it in production. + + + +This integration connects Sentry with the [Laravel AI](https://laravel.com/docs/ai) package. +The integration has been confirmed to work with `sentry/sentry-laravel` version `4.27.0` and above. + + + +Once you've installed this SDK, you can use the [AI Agents Dashboards](https://sentry.io/orgredirect/organizations/:orgslug/dashboards/?filter=onlyPrebuilt&query=agents&sort=mostPopular) to understand what's going on with your AI agents. + +Sentry AI Agents monitoring will automatically collect information about agents, tools, prompts, tokens, and models. + +## Prerequisites + +- Laravel 12.x or later +- `sentry/sentry-laravel` version `4.27.0` or later +- An AI provider configured for Laravel AI +- Tracing set up in your Sentry configuration + +## Install + +Install the `sentry/sentry-laravel` package: + +```bash +composer require sentry/sentry-laravel +``` + +Install and configure `laravel/ai`: + +```bash +composer require laravel/ai +php artisan vendor:publish --provider="Laravel\Ai\AiServiceProvider" +php artisan migrate +``` + +Add your AI provider API keys to your `.env` file: + +```shell {filename:.env} +ANTHROPIC_API_KEY=your-anthropic-key +OPENAI_API_KEY=your-openai-key +... +``` + +## Configure + +The Laravel AI integration is enabled automatically when both `sentry/sentry-laravel` and `laravel/ai` are installed and tracing is active. No additional configuration is needed. + +Make sure tracing is enabled in your `.env`: + +```shell {filename:.env} +SENTRY_TRACES_SAMPLE_RATE=1.0 +``` + +To include LLM inputs and outputs (prompts, tool arguments, and responses), enable the `send_default_pii` option: + +```shell {filename:.env} +SENTRY_SEND_DEFAULT_PII=true +``` + + + +Sentry considers LLM and tool inputs/outputs as PII and doesn't include them by default. Set `send_default_pii` to `true` to capture this data for debugging. See Data Collected for more info. + + + +## Verify + +Verify that the integration works by creating an agent with a tool and prompting it. The resulting data should show up in your AI Agents dashboard. + +First, create an agent and a tool: + +```bash +php artisan make:agent TimeAgent +php artisan make:tool GetCurrentTime +``` + +Update the tool to return the current time: + +```php {filename:app/Ai/Tools/GetCurrentTime.php} +toDateTimeString(); + } + + public function schema(JsonSchema $schema): array + { + return []; + } +} +``` + +Register the tool on the agent: + +```php {filename:app/Ai/Agents/TimeAgent.php} +prompt('What time is it?'); + + return $response->text; +}); +``` + +Visiting this route will trigger an AI agent invocation that will be captured by Sentry. It may take a couple of moments for the data to appear in [sentry.io](https://sentry.io). + +## Behavior + +The following data is captured automatically: + +- **Agent invocations** — `gen_ai.invoke_agent` spans for each agent prompt +- **LLM requests** — `gen_ai.chat` spans for each HTTP request to an AI provider +- **Tool executions** — `gen_ai.execute_tool` spans when agents call tools +- **Embeddings** — `gen_ai.embeddings` spans for embedding generation +- **Token usage** — input and output token counts per request +- **Model and provider info** — which model and provider were used + +Streaming agent responses are also fully supported. The integration captures span data for both `prompt()` and `stream()` calls. + +### Conversations + +If your agent implements `Conversational` and uses the `RemembersConversations` trait, Sentry automatically tracks the `conversationId` returned by Laravel AI. The integration adds it to AI spans as `gen_ai.conversation.id`, which lets Sentry group multiple prompts into the same conversation in **Explore > Conversations**. + +To continue a conversation, pass the previous `$response->conversationId` back into Laravel AI with `continue()`: + +```php +use App\Ai\Agents\TimeAgent; +use App\Models\User; + +$user = User::firstOrFail(); +$conversationId = null; + +foreach (['Hello', 'What did I just ask you?'] as $message) { + $agent = $conversationId + ? (new TimeAgent)->continue($conversationId, as: $user) + : (new TimeAgent)->forUser($user); + + $response = $agent->prompt($message); + $conversationId = $response->conversationId; +} +``` + +Both prompts will appear under the same conversation because Laravel AI reuses the same `conversationId`. For CLI commands and other non-HTTP entry points, create a transaction around each agent call so the AI spans are captured. + +## Options + +You can selectively disable individual span types in `config/sentry.php` under the `tracing` > `features` key: + +```php {filename:config/sentry.php} +'tracing' => [ + 'features' => [ + // Master switch for all AI spans (requires laravel/ai) + 'gen_ai' => env('SENTRY_TRACE_GEN_AI_ENABLED', true), + + // Individual span types + 'gen_ai_invoke_agent' => env('SENTRY_TRACE_GEN_AI_INVOKE_AGENT_ENABLED', true), + 'gen_ai_chat' => env('SENTRY_TRACE_GEN_AI_CHAT_ENABLED', true), + 'gen_ai_execute_tool' => env('SENTRY_TRACE_GEN_AI_EXECUTE_TOOL_ENABLED', true), + 'gen_ai_embeddings' => env('SENTRY_TRACE_GEN_AI_EMBEDDINGS_ENABLED', true), + ], +], +``` + +Setting `gen_ai` to `false` disables all AI tracing. The individual options let you turn off specific span types while keeping others active. + +## Supported Versions + +- Laravel: 12.x+ +- `sentry/sentry-laravel`: 4.27.0+ +- `laravel/ai`: 0.x+ +- PHP: 8.2+ diff --git a/docs/platforms/php/guides/laravel/tracing/instrumentation/automatic-instrumentation.mdx b/docs/platforms/php/guides/laravel/tracing/instrumentation/automatic-instrumentation.mdx index 7fafd83808ceb8..d284507fb77859 100644 --- a/docs/platforms/php/guides/laravel/tracing/instrumentation/automatic-instrumentation.mdx +++ b/docs/platforms/php/guides/laravel/tracing/instrumentation/automatic-instrumentation.mdx @@ -19,6 +19,7 @@ Automatic instrumentation is also available with the following packages: - [Lighthouse](https://lighthouse-php.com/) GraphQL operations - [Laravel Folio](https://laravel.com/docs/11.x/folio) page based routes - [Laravel Livewire](https://livewire.laravel.com/) components +- [Laravel AI](https://laravel.com/docs/ai) agent invocations, LLM requests, tool executions, and embeddings (see Laravel AI integration) The Laravel SDK is also capable of creating spans for filesystem access operations. You can enable this feature by wrapping the configuration for all disks From a1b517912c809daaab96952c3d7203b1307c9d89 Mon Sep 17 00:00:00 2001 From: Fabian Schindler Date: Fri, 26 Jun 2026 08:18:29 +0200 Subject: [PATCH 2/2] Update docs/platforms/php/guides/laravel/integrations/laravel-ai.mdx Co-authored-by: Alex Krawiec --- docs/platforms/php/guides/laravel/integrations/laravel-ai.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/php/guides/laravel/integrations/laravel-ai.mdx b/docs/platforms/php/guides/laravel/integrations/laravel-ai.mdx index f8014c09dc8fdc..974024ae8bef16 100644 --- a/docs/platforms/php/guides/laravel/integrations/laravel-ai.mdx +++ b/docs/platforms/php/guides/laravel/integrations/laravel-ai.mdx @@ -3,7 +3,7 @@ title: Laravel AI description: "Learn about using Sentry for Laravel AI agent monitoring." --- - + Laravel AI support is in beta. Test locally before using it in production.