> ## 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.

# المراقبة

> اقرأ حالة تشغيل الوكيل واستخدامه وتكلفته، وتتبّع كل خطوة حتى طلب Gateway الخاص بها.

اقرأ نتيجة التشغيل لترى كيف انتهى، وكم كلّف، وأي طلب Gateway خدم كل دور للنموذج. تتضمن كل نتيجة المخرجات النهائية، وسجل التشغيل مع حالته، والاستخدام التراكمي، وسجلًا واحدًا لكل خطوة يتضمن معرّف الطلب والمزوّد والنموذج.

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

console.log(result.output);            // final value
console.log(result.run.status);        // completed, stopped, waiting_for_human or cancelled
console.log(result.usage.totalTokens); // summed over all steps
console.log(result.usage.cost);        // as reported by the gateway
```

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

print(result.output)              # final value
print(result.run.status)          # completed, stopped or waiting_for_human
print(result.usage.total_tokens)  # summed over all steps
print(result.usage.cost)          # as reported by the gateway
```

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

fmt.Println(result.Output)            // final value
fmt.Println(result.Run.Status)        // completed, stopped, or waiting_for_human
fmt.Println(result.Usage.TotalTokens) // summed over all steps
fmt.Println(result.Usage.Cost)        // as reported by the gateway
```

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

Console.WriteLine(result.Output);            // final value
Console.WriteLine(result.Run.Status);        // completed, stopped, or waiting_for_human
Console.WriteLine(result.Usage.TotalTokens); // summed over all steps
Console.WriteLine(result.Usage.Cost);        // as reported by the gateway
```

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

echo $result->output;                 // final value
echo $result->run->status;            // completed, stopped, or waiting_for_human
echo $result->usage["total_tokens"];  // summed over all steps
echo $result->usage["cost"];          // as reported by the gateway
```

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

puts result.output               # final value
puts result.run.status           # completed, stopped, or waiting_for_human
puts result.usage[:total_tokens] # summed over all steps
puts result.usage[:cost]         # as reported by the gateway
```

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

System.out.println(result.output());              // final value
System.out.println(result.run().status());        // completed, stopped, or waiting_for_human
System.out.println(result.usage().totalTokens()); // summed over all steps
System.out.println(result.usage().cost());        // as reported by the gateway
```

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

println!("{}", result.output);              // final value
println!("{}", result.run.status);          // completed, stopped, or waiting_for_human
println!("{}", result.usage.total_tokens);  // summed over all steps
println!("{:?}", result.usage.cost);        // supplied by the model client
```

## اقرأ الاستخدام والتكلفة

يتضمن الاستخدام رموز الإدخال والإخراج والمخزّنة مؤقتًا والإجمالية، إضافة إلى التكلفة: `inputTokens` و`outputTokens` و`cachedTokens` و`totalTokens` و`cost` في TypeScript وJava؛ و`input_tokens` وما شابهها في Python وPHP وRuby وRust؛ و`InputTokens` وما شابهها في Go وC#. ولكل خطوة أيضًا استخدامها الخاص.

| اللغة | موضع الاستخدام | تنبيه |
| - | - | - |
| TypeScript، Python، Go، C#، Java | `usage` في النتيجة | |
| PHP | `$result->usage`، وهو مصفوفة | تتركه النتيجة الموقوفة مؤقتًا فارغًا؛ اقرأ `$result->run->usage` |
| Ruby | `result.usage`، وهو Hash بمفاتيح رمزية | تتركه النتيجة الموقوفة مؤقتًا غير مضبوط؛ اقرأ `result.run.usage` |
| Rust | `result.usage` (`UsageSummary`) | يملأ محوّل Gateway المدمج في `0.2` الحقل `cost` فقط من حقل رقمي `meta.cost` أو `cost`، ولا يحوّل `cost_nanos` أو `cost_cents`. استخدم استجابة Gateway أو سجل التوليد لتقارير الإنفاق. |

## تحقّق من طريقة انتهاء التشغيل

حالات التشغيل هي `queued` و`running` و`waiting_for_tools` و`waiting_for_human` و`completed` و`stopped` و`failed`؛ وتضيف TypeScript الحالة `cancelled`. النتيجة التي تعود إليك تكون `completed`، أو `stopped` (تطابق [شرط إيقاف](https://phaseo.app/docs/ar/v1/sdk-reference/agent/stop-conditions.md)، والسبب في سبب إيقاف التشغيل)، أو `waiting_for_human` (راجع [الحالة والموافقة](https://phaseo.app/docs/ar/v1/sdk-reference/agent/state-and-approval.md))، أو `cancelled` في TypeScript. أما عمليات التشغيل الفاشلة فترمي خطأً أو تعيده بدلًا من ذلك؛ راجع [الأحداث والأخطاء](https://phaseo.app/docs/ar/v1/sdk-reference/agent/events-and-errors.md).

## تتبّع خطوة حتى طلب Gateway الخاص بها

يربط سجل كل خطوة دورًا واحدًا للنموذج بطلب Gateway الذي خدمه. ابحث عن معرّف الطلب في سجلات Phaseo، أو عن معرّف الاستجابة الأصلي لدى المزوّد الأصلي.

| حقل الخطوة | camelCase (TypeScript، PHP، Java) | snake\_case (Python، Ruby، Rust) | PascalCase (Go، C#) |
| - | - | - | - |
| معرّف طلب Gateway | `requestId` | `request_id` | `RequestID` (Go)، `RequestId` (C#) |
| معرّف الاستجابة لدى المزوّد الأصلي | `nativeResponseId` | `native_response_id` (غير موجود في Rust) | `NativeResponseID` (Go)، `NativeResponseId` (C#) |
| المزوّد والنموذج | `provider`، `model` | `provider`، `model` | `Provider`، `Model` |
| سبب الانتهاء | `finishReason` | `finish_reason` | `FinishReason` |
| المحاولات، بما فيها إعادة المحاولات | `modelAttempts` | `model_attempts` | `ModelAttempts` |
| استدعاءات الأدوات | `toolCalls` | `tool_calls` | `ToolCalls` |
| الخطأ | `error` (وتضيف TypeScript `errorDetails`) | `error` | `Error` |
| كتلة meta من Gateway والتحذيرات | `responseMeta`، `warnings` | `response_meta`، `warnings` (غير موجودة في Rust) | `ResponseMeta`، `Warnings` |

توجد الخطوات في `steps` على النتيجة (`Steps` في Go وC#، و`steps()` في Java). سجلات الخطوات في Python من النوع `AgentStepRecord`؛ وتسميها اللغات الأخرى `RunStep`.

## سجّل عمليات التشغيل في الإنتاج

سجّل معرّف التشغيل وفهرس الخطوة ومعرّف الطلب ومعرّف الاستجابة الأصلي والمزوّد والنموذج وسبب الانتهاء ومعرّف استدعاء الأداة وسبب الإيقاف. تمنحك [خطافات دورة الحياة](https://phaseo.app/docs/ar/v1/sdk-reference/agent/lifecycle-hooks.md) كل ذلك أثناء حدوث التشغيل، وتحمل أحداث `run.failed` نص الخطأ حيث ترسلها لغتك. لا تسجّل المطالبات الخام أو مدخلات الأدوات أو بيانات الاعتماد؛ احجبها قبل أن تغادر الأحداث عمليتك.

للحصول على سجل محلي لعمليات تشغيل كاملة أثناء التطوير، استخدم [DevTools](https://phaseo.app/docs/ar/v1/sdk-reference/agent/devtools.md) بدلًا من ذلك.


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