---
title: Laravel SDK
description: Auto-capture every laravel/ai call (cost, tokens, latency, quality) with a Composer install and one env var.
section: sdks
order: 4
---

# Laravel SDK

Report cost, latency, and quality for the AI agents in your Laravel app. If you use [`laravel/ai`](https://github.com/laravel/ai), every prompt and embedding is captured automatically, no code changes. The SDK is non-blocking and never throws into your app.

## Install

Until we are on Packagist, add the repository, then require the package:

```json
"repositories": [
  { "type": "vcs", "url": "https://github.com/agent-ping/agent-ping-laravel" }
]
```

```bash
composer require agentping/laravel:^0.1
```

Set your API key. The ingest region is read from the key, so there is nothing else to configure:

```env
AGENTPING_API_KEY=apk_eu_...
```

Requires PHP 8.2+. The service provider is auto-discovered.

## Automatic instrumentation

With `laravel/ai` installed, every prompt, stream, and embedding is reported, with provider, model, token usage, latency, and cost:

```php
$reply = (new SalesCoach)->prompt('Score this email: ...');  // captured automatically
```

Disable it any time with `AGENTPING_LISTEN_TO_AI_SDK=false`.

## Naming your agents

Runs are grouped by agent name in Spend and Pulse. The name is resolved in this order:

1. **An active run**: `AgentPing::run('name')` or `AgentPing::agent('name', fn () => ...)`.
2. **`AgentPing::useAgent('name')`**: set once at the top of a request, job, or command; every auto-captured call in that scope uses it (reset automatically afterwards).
3. **A named Agent class**: a `laravel/ai` Agent class like `MorningBriefing` is auto-named `morning_briefing`, no extra code.
4. **`AGENTPING_DEFAULT_AGENT`** (default `ai-agent`).

The anonymous `agent($prompt)->prompt(...)` helper carries no name, so for those calls use one of the first two. Either name the whole scope once:

```php
use AgentPing\Laravel\Facades\AgentPing;

AgentPing::useAgent('morning-briefing');
$summary = agent($systemPrompt)->prompt($userMessage, provider: 'anthropic');
```

or wrap a single call to also group it as one run:

```php
$summary = AgentPing::agent('morning-briefing', fn () =>
    agent($systemPrompt)->prompt($userMessage, provider: 'anthropic')
);
```

If you define your agents as classes instead of the `agent()` helper, naming is automatic.

## Manual tracking

For agents that do not use `laravel/ai`, track runs directly:

```php
use AgentPing\Laravel\Facades\AgentPing;

$run = AgentPing::run('support-triage', customerId: 'acme', feature: 'ticket-routing');

$run->event('llm_call', [
    'provider' => 'anthropic',
    'model' => 'claude-sonnet-4-6',
    'input_tokens' => 1200,
    'output_tokens' => 480,
]);

$run->finish('success', scores: ['confidence' => 0.92]);
```

Nest sub-agents by passing `parentRunId:` (or set the `AGENTPING_PARENT_RUN` env var) to build a run tree.

## Heartbeats

For cron jobs and scheduled tasks, report one completion per run:

```php
AgentPing::heartbeat('daily-summary', status: 'ok', costUsd: 0.084, durationMs: 12_300);
```

## Queue workers

Telemetry flushes automatically at the end of each web request, console command, and queued job. **Restart Horizon and your queue workers after deploying** so they load the new code and key. For a custom long-running loop, call `AgentPing::flush()`.

## Configuration

| Variable | Default | Description |
|----------|---------|-------------|
| `AGENTPING_API_KEY` | required | Region-scoped team key (`apk_...`). |
| `AGENTPING_DEFAULT_AGENT` | `ai-agent` | Name for un-named auto-captured calls. |
| `AGENTPING_LISTEN_TO_AI_SDK` | `true` | Auto-instrument `laravel/ai`. |
| `AGENTPING_PARENT_RUN` | optional | Parent run id for nesting. |

Run `php artisan vendor:publish --tag=agentping-config` for the full config (queue size, batch size, timeouts). Use a team key for the SDK; `ping_...` tokens are for URLs only.

[Source on GitHub](https://github.com/agent-ping/agent-ping-laravel)