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

# البث في Agent SDK

> اعرض نص الوكيل واستدلاله ونشاط أدواته أثناء تقدّم التشغيل.

استدعِ دالة البث في الوكيل بدلًا من دالة التشغيل لعرض النص ونشاط الأدوات أثناء تقدّم التشغيل. تشغّل الدالة الحلقة نفسها القابلة للاستئناف فوق بث SSE من Responses في Gateway، وتفعل دالة متابعة البث الشيء نفسه للتشغيل الموقوف مؤقتًا. لا يتوفر البث في Rust.

## بثّ النص

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

for await (const delta of result.getTextStream()) {
  process.stdout.write(delta);
}

const completed = await result.getResult();
console.log(completed.run.status);
```

```python Python theme={null}
stream = agent.stream(input="Research this topic", client=client)

for delta in stream.text_stream():
    print(delta, end="", flush=True)

completed = stream.result()
```

```go Go theme={null}
stream := agent.Stream(ctx, phaseoagent.RunOptions{Input: input, Client: client})

for delta := range stream.Text() {
  fmt.Print(delta)
}

completed, err := stream.Result()
```

```csharp C# theme={null}
var stream = agent.Stream(new RunOptions { Input = input, Client = client });

await foreach (var delta in stream.TextStream())
{
    Console.Write(delta);
}

var completed = await stream.GetResult();
```

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

foreach ($stream->textStream() as $delta) {
    echo $delta;
}

$completed = $stream->getResult();
```

```ruby Ruby theme={null}
stream = agent.stream(input: "Research this topic", client: client)

stream.text_stream.each { |delta| print delta }

completed = stream.result
```

```java Java theme={null}
// textStream() blocks until the run finishes; print live deltas from onEvent instead.
var options = new AgentSdk.RunOptions(
    input, AgentSdk.createGatewayAgentClient(), null, null, null, null, null, null,
    event -> {
        if (event.type().equals("response.output_text.delta")) {
            System.out.print(event.details().get("delta"));
        }
    },
    null);
var completed = agent.stream(options).getResult();
```

النتيجة النهائية هي نتيجة التشغيل نفسها التي تعيدها دالة التشغيل. وتختلف طريقة عمل البث حسب اللغة:

> [tab] TypeScript
>
> تعيد `agent.stream()` و`agent.continueStream()` نتيجة بث فورًا. وتُحل `getResult()` عند انتهاء التشغيل.

> [tab] Python
>
> تشغّل `agent.stream(...)` و`agent.continue_stream(...)` الحلقة في خيط في الخلفية وتعيدان `AgentStreamResult` قابلة لإعادة التشغيل. وتنتظر `result()` التشغيل.

> [tab] Go
>
> تبدأ `agent.Stream` و`agent.ContinueStream` التشغيل في goroutine وتعيدان `*StreamResult` فورًا. وتحجب `Result()` حتى ينتهي التشغيل.

> [tab] C#
>
> تبدأ `agent.Stream` و`agent.ContinueStream` التشغيل وتعيدان `AgentStreamResult` فورًا. وتكتمل `GetResult()` عند انتهاء التشغيل.

> [tab] PHP
>
> تعيد `$agent->stream()` و`$agent->continueStream()` القيمة `AgentStreamResult`. لا يوجد في PHP خيط في الخلفية: يتقدّم التشغيل داخل Fiber فقط بينما تسحب شيفرتك الحدث التالي، وتستنزف `getResult()` الأحداث المتبقية. يناسب ذلك نصوص CLI وعمّال الطلبات؛ أما لواجهة مباشرة، فكرّر داخل الطلب الذي يخدم الاستجابة، أو شغّل الوكيل في عامل وادفع الأحداث إلى المتصفح بنفسك.
>
> تأخذ `stream()` فقط `input` و`client` و`context` و`state`؛ استخدم `run()` للخيارات الأخرى.

> [tab] Ruby
>
> تبدأ `agent.stream` و`agent.continue_stream` التشغيل على خيط عامل وتعيدان `StreamResult` فورًا. تنضم `result` إلى الخيط، وتعيد رفع أي خطأ، وتعيد نتيجة التشغيل.
>
> تأخذ `stream` فقط `input:` و`client:` و`context:` و`state:`؛ استخدم `run` للخيارات الأخرى.

> [tab] Java
>
> تبدأ `agent.stream` و`agent.continueStream` التشغيل على خيط خفي (daemon) باسم `phaseo-agent-stream` وتعيدان `StreamResult` فورًا. تعيد `textStream()` و`fullStream()` قوائم وتحجبان حتى ينتهي التشغيل، لذا فإن حلقة على `textStream()` تطبع الإجابة كاملة في النهاية. للتصرف بناءً على الأحداث أثناء سير التشغيل، مرّر مستهلك `onEvent` في `RunOptions`، كما في المثال أعلاه.

> [tab] Rust
>
> لا يتوفر البث في `phaseo-agent` 0.2. استدعِ `run_with_events` أو `continue_with_events` للحصول على أحداث دورة الحياة عبر دالة رد نداء، واقرأ النص من التشغيل المكتمل.

## اختر بثًّا

يعيد كل مستهلك تشغيل الأحداث من البداية، لذا يمكن لمُعارض واجهة ومسجّل وشيفرة حفظ أن يقرأوا التشغيل نفسه دون طلب ثانٍ إلى النموذج.

| يُنتج | TypeScript | Python | Go | C# | PHP | Ruby | Java |
| - | - | - | - | - | - | - | - |
| أجزاء نص الإجابة | `getTextStream()` | `text_stream()` | `Text()` | `TextStream()` | `textStream()` | `text_stream` | `textStream()` (قائمة) |
| أجزاء الاستدلال | `getReasoningStream()` | `reasoning_stream()` | `Events()` مع التصفية | `FullStream()` مع التصفية | `reasoningStream()` | `reasoning_stream` | `fullStream()` مع التصفية |
| عناصر الخط الزمني | `getItemsStream()` (محددة النوع) | `item_stream()` (قواميس) | `Events()` مع التصفية | `FullStream()` مع التصفية | `itemStream()` | `item_stream` | `fullStream()` مع التصفية |
| أحداث دورة حياة الأدوات | `getToolStream()` | `tool_stream()` | `Events()` مع التصفية | `FullStream()` مع التصفية | `fullStream()` مع التصفية | `full_stream` مع التصفية | `fullStream()` مع التصفية |
| كل الأحداث | `getFullStream()`، ثم حدث `result` نهائي | `full_stream()` | `Events()` (قناة) | `FullStream()` (`IAsyncEnumerable`) | `fullStream()` | `full_stream` (`Enumerator`) | `fullStream()` (قائمة، بعد التشغيل) |

تتضمن TypeScript أيضًا `getText()` لانتظار الإجابة كاملة، بحيث يمكن تنفيذ العرض والحفظ جنبًا إلى جنب:

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

const [text, completed] = await Promise.all([
  result.getText(),
  result.getResult(),
]);
```

أحداث النموذج هي `response.output_text.delta` و`response.reasoning.delta` و`response.item`؛ وتجد حقولها في صفحة [العناصر](https://phaseo.app/docs/ar/v1/sdk-reference/agent/items.md). لا تُبث أحداث النموذج إلا عندما يدعم العميل البث، كما تفعل كل عملاء Gateway. مع عميل نموذج آخر (لا ينفّذ `StreamingModelClient` أو `IStreamingModelClient` أو لا يستجيب لـ `stream`)، يظل البث يُطلق أحداث دورة الحياة لكن دون أجزاء نصية.

## بثّ تقدّم الأدوات

تنشر الأدوات التي تبلّغ عن التقدّم أحداث `tool.preliminary_result`، التي تظهر في البث الكامل (وفي بث الأدوات في TypeScript) وتبقى مرتبطة بالخطوة المكتملة. توضح صفحة [الأدوات](https://phaseo.app/docs/ar/v1/sdk-reference/agent/tools.md#report-progress-and-update-context) كيف تبلّغ كل لغة عن التقدّم.

## ألغِ البث

| اللغة | الاستدعاء | ما يحدث |
| - | - | - |
| TypeScript | `cancel()` | يُلغي التشغيل. تتلقى الأدوات المحلية الإلغاء عبر `context.signal`. |
| Python | `cancel()` | يغلق طلب النموذج النشط؛ ويرفع التشغيل `InterruptedError` |
| Go | `stream.Cancel()` | يُلغي السياق الممرّر إلى التشغيل، ما يوقف طلب النموذج؛ وتعيد `Result()` خطأً |
| C# | `stream.Cancel()`، أو إلغاء `RunOptions.CancellationToken` | يُلغي رمزًا مرتبطًا يصل إلى طلب النموذج وإلى `runtime.CancellationToken` لكل أداة؛ وترمي `GetResult()` استثناءً |
| PHP | `$stream->cancel()` | يرمي `Agent stream cancelled` داخل Fiber، ما يوقف التشغيل عند نقطة التعليق التالية |
| Ruby | `stream.cancel` | ينهي الخيط العامل، ما يغلق بث HTTP وينهي كل مُعدِّد |
| Java | `stream.cancel()` | يقاطع الخيط العامل وقراءة HTTP، ويُلغي future النتيجة؛ وترمي `getResult()` استثناءً |
| Rust | غير مدعوم | عمليات التشغيل متزامنة |

تحتفظ كل خطوة مكتملة بمعرّف الطلب والمزوّد والنموذج وسبب الانتهاء والتحذيرات والاستخدام.


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