> ## Documentation Index
> Fetch the complete documentation index at: https://phaseo.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Phaseo Gateway base URL: https://api.phaseo.app/v1. Send `Authorization: Bearer $PHASEO_API_KEY` with every request.
> Model IDs look like `provider/model`, for example `openai/gpt-6-astra`. Do not guess IDs: list them with `GET /v1/models` or check https://phaseo.app/models. `phaseo/free` routes to an available free model and needs no wallet balance.
> For new text integrations prefer `POST /v1/responses`. `POST /v1/chat/completions` (OpenAI format) and `POST /v1/messages` (Anthropic format) suit existing code.
> The full API contract is https://phaseo.app/docs/openapi/v1/openapi.yaml. Official SDKs: `@phaseo/sdk` (TypeScript) and `phaseo` (Python), plus Go, C#, PHP, Ruby and Rust.
> Search these docs over MCP at https://phaseo.app/docs/mcp, and install Phaseo skills with `npx skills add https://phaseo.app/docs`. If a page is wrong or out of date, report it with the MCP `submit_feedback` tool.
> Manage Phaseo accounts with the `phaseo` CLI (`npm install -g @phaseo/cli`, then `phaseo login` or `phaseo login --device-code`), the `/v1` Management API or the MCP server at `https://mcp.phaseo.app/mcp?access=manage`. Do not send users to the dashboard for account tasks. A person is still needed for sign-up, approving a sign-in, paying the first top-up on the checkout link that `phaseo credits add` returns when no card is saved, confirming each saved-card top-up from the emailed link, and account security (password, MFA, passkeys). Create API keys with `phaseo keys create --name <name> --json`; never guess one. Credit top-ups need `phaseo login --scopes billing:write` first. Task map: https://phaseo.app/docs/v1/developers/manage-from-an-agent.md.

# Beobachtbarkeit

> Status, Nutzung und Kosten eines Agentenlaufs lesen und jeden Schritt bis zu seiner Gateway-Anfrage zurückverfolgen.

Lies das Laufergebnis, um zu sehen, wie ein Lauf endete, was er gekostet hat und welche Gateway-Anfrage jeden Modell-Turn bedient hat. Jedes Ergebnis enthält die endgültige Ausgabe, den Laufeintrag mit seinem Status, die kumulierte Nutzung und einen Eintrag pro Schritt mit Request-ID, Anbieter und Modell.

```typescript TypeScript theme={null}
const result = await agent.run({ input, client });

console.log(result.output);            // endgültiger Wert
console.log(result.run.status);        // completed, stopped, waiting_for_human oder cancelled
console.log(result.usage.totalTokens); // über alle Schritte summiert
console.log(result.usage.cost);        // wie vom Gateway gemeldet
```

```python Python theme={null}
result = agent.run(input=prompt, client=client)

print(result.output)              # endgültiger Wert
print(result.run.status)          # completed, stopped oder waiting_for_human
print(result.usage.total_tokens)  # über alle Schritte summiert
print(result.usage.cost)          # wie vom Gateway gemeldet
```

```go Go theme={null}
result, err := agent.Run(ctx, phaseoagent.RunOptions{Input: prompt, Client: client})
if err != nil {
  return err
}

fmt.Println(result.Output)            // endgültiger Wert
fmt.Println(result.Run.Status)        // completed, stopped oder waiting_for_human
fmt.Println(result.Usage.TotalTokens) // über alle Schritte summiert
fmt.Println(result.Usage.Cost)        // wie vom Gateway gemeldet
```

```csharp C# theme={null}
var result = await agent.Run(new RunOptions { Input = prompt, Client = client });

Console.WriteLine(result.Output);            // endgültiger Wert
Console.WriteLine(result.Run.Status);        // completed, stopped oder waiting_for_human
Console.WriteLine(result.Usage.TotalTokens); // über alle Schritte summiert
Console.WriteLine(result.Usage.Cost);        // wie vom Gateway gemeldet
```

```php PHP theme={null}
$result = $agent->run(input: $prompt, client: $client);

echo $result->output;                 // endgültiger Wert
echo $result->run->status;            // completed, stopped oder waiting_for_human
echo $result->usage["total_tokens"];  // über alle Schritte summiert
echo $result->usage["cost"];          // wie vom Gateway gemeldet
```

```ruby Ruby theme={null}
result = agent.run(input: prompt, client: client)

puts result.output               # endgültiger Wert
puts result.run.status           # completed, stopped oder waiting_for_human
puts result.usage[:total_tokens] # über alle Schritte summiert
puts result.usage[:cost]         # wie vom Gateway gemeldet
```

```java Java theme={null}
var result = agent.run(options);

System.out.println(result.output());              // endgültiger Wert
System.out.println(result.run().status());        // completed, stopped oder waiting_for_human
System.out.println(result.usage().totalTokens()); // über alle Schritte summiert
System.out.println(result.usage().cost());        // wie vom Gateway gemeldet
```

```rust Rust theme={null}
let result = agent.run(&mut client, RunOptions::new("Explain when to use routing presets."))?;

println!("{}", result.output);              // endgültiger Wert
println!("{}", result.run.status);          // completed, stopped oder waiting_for_human
println!("{}", result.usage.total_tokens);  // über alle Schritte summiert
println!("{:?}", result.usage.cost);        // vom Modell-Client geliefert
```

## Nutzung und Kosten lesen

Die Nutzung umfasst Eingabe-, Ausgabe-, gecachte und Gesamt-Tokens sowie Kosten: `inputTokens`, `outputTokens`, `cachedTokens`, `totalTokens`, `cost` in TypeScript und Java; `input_tokens` usw. in Python, PHP, Ruby und Rust; `InputTokens` usw. in Go und C#. Jeder Schritt hat außerdem seine eigene Nutzung.

| Sprache | Wo die Nutzung liegt | Einschränkung |
| - | - | - |
| TypeScript, Python, Go, C#, Java | `usage` im Ergebnis | |
| PHP | `$result->usage`, ein Array | Bei einem pausierten Ergebnis ist es leer; lies `$result->run->usage` |
| Ruby | `result.usage`, ein Hash mit Symbol-Schlüsseln | Bei einem pausierten Ergebnis ist es nicht gesetzt; lies `result.run.usage` |
| Rust | `result.usage` (`UsageSummary`) | Der eingebaute Gateway-Adapter von `0.2` füllt `cost` nur aus einem numerischen Feld `meta.cost` oder `cost` und übernimmt `cost_nanos` oder `cost_cents` nicht. Für Ausgabenberichte verwendest du die Gateway-Antwort oder den Generierungseintrag. |

## Prüfen, wie der Lauf endete

Die Laufstatus sind `queued`, `running`, `waiting_for_tools`, `waiting_for_human`, `completed`, `stopped` und `failed`; TypeScript ergänzt `cancelled`. Ein Ergebnis, das du zurückbekommst, ist `completed`, `stopped` (eine [Stoppbedingung](https://phaseo.app/docs/de/v1/sdk-reference/agent/stop-conditions.md) hat zugetroffen, mit dem Grund im Stoppgrund des Laufs), `waiting_for_human` (siehe [Status und Freigabe](https://phaseo.app/docs/de/v1/sdk-reference/agent/state-and-approval.md)) oder, in TypeScript, `cancelled`. Fehlgeschlagene Läufe werfen stattdessen einen Fehler oder geben ihn zurück; siehe [Events und Fehler](https://phaseo.app/docs/de/v1/sdk-reference/agent/events-and-errors.md).

## Einen Schritt bis zu seiner Gateway-Anfrage verfolgen

Jeder Schritteintrag verknüpft einen Modell-Turn mit der Gateway-Anfrage, die ihn bedient hat. Suche die Request-ID in deinen Phaseo-Logs oder die native Response-ID beim ursprünglichen Anbieter.

| Schrittfeld | camelCase (TypeScript, PHP, Java) | snake\_case (Python, Ruby, Rust) | PascalCase (Go, C#) |
| - | - | - | - |
| Gateway-Request-ID | `requestId` | `request_id` | `RequestID` (Go), `RequestId` (C#) |
| Upstream-Response-ID | `nativeResponseId` | `native_response_id` (nicht in Rust) | `NativeResponseID` (Go), `NativeResponseId` (C#) |
| Anbieter und Modell | `provider`, `model` | `provider`, `model` | `Provider`, `Model` |
| Finish-Reason | `finishReason` | `finish_reason` | `FinishReason` |
| Versuche, einschließlich Wiederholungen | `modelAttempts` | `model_attempts` | `ModelAttempts` |
| Tool-Aufrufe | `toolCalls` | `tool_calls` | `ToolCalls` |
| Fehler | `error` (TypeScript ergänzt `errorDetails`) | `error` | `Error` |
| Meta-Block und Warnungen des Gateways | `responseMeta`, `warnings` | `response_meta`, `warnings` (nicht in Rust) | `ResponseMeta`, `Warnings` |

Die Schritte liegen in `steps` im Ergebnis (`Steps` in Go und C#, `steps()` in Java). Schritteinträge in Python sind `AgentStepRecord`; die anderen Sprachen nennen sie `RunStep`.

## Läufe in der Produktion aufzeichnen

Protokolliere Lauf-ID, Schrittindex, Request-ID, native Response-ID, Anbieter, Modell, Finish-Reason, Tool-Call-ID und Stoppgrund. [Lifecycle-Hooks](https://phaseo.app/docs/de/v1/sdk-reference/agent/lifecycle-hooks.md) liefern dir all das während des Laufs, und `run.failed`-Events enthalten den Fehlertext, wo deine Sprache sie sendet. Protokolliere keine rohen Prompts, Tool-Eingaben oder Zugangsdaten; schwärze sie, bevor Events deinen Prozess verlassen.

Für eine lokale Aufzeichnung ganzer Läufe während der Entwicklung verwendest du stattdessen [DevTools](https://phaseo.app/docs/de/v1/sdk-reference/agent/devtools.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.