مرجع Rust Agent SDK API

تصف هذه الصفحة واجهة API العامة لـ phaseo-agent 0.1.

تعريف الوكيل

واجهة API	الغرض
`AgentDefinition::new(id, model)`	إنشاء تعريف وكيل بحد افتراضي من ثماني خطوات.
`.instructions(text)`	تعيين تعليمات النموذج.
`.tool(tool)`	إضافة أداة.
`.max_steps(limit)`	تعيين حد أدوار النموذج، على ألا يقل عن واحد.
`.model_retries(count, backoff)`	إعادة طلبات النموذج الفاشلة بفاصل `Duration` ثابت.
`.human_review(callback)`	إيقاف الجولة مؤقتًا بعد رد النموذج إذا أعادت دالة callback القيمة `Some(HumanReviewRequest)`.
`create_agent(definition)`	إنشاء `Agent`.

التشغيل والمتابعة

الأسلوب	الغرض
`Agent::run(client, options)`	التشغيل بالتزامن من دون callback للأحداث.
`Agent::run_with_events(client, options, callback)`	التشغيل بالتزامن وإصدار قيم `AgentEvent`.
`Agent::continue_run(client, options)`	متابعة جولة متوقفة مؤقتًا.
`Agent::continue_with_events(client, options, callback)`	متابعة الجولة وإصدار الأحداث.

حقول RunOptions:

input: Value
context: Value
model: Option<String>
max_steps: Option<usize>

أنشئ القيم الافتراضية باستخدام RunOptions::new(input). حقول ContinueOptions:

result: RunResult
human_input: Option<String>
approvals: Vec<ToolDecision>
tool_outputs: Vec<ToolOutput>

أنشئ القيم الافتراضية باستخدام ContinueOptions::new(result).

الأدوات

واجهة API	الغرض
`Tool::new(id, description, parameters, executor)`	تعريف أداة محلية متزامنة.
`Tool::external(id, description, parameters)`	تعريف أداة يقدّم التطبيق نتيجتها بعد إيقاف مؤقت.
`Tool::require_approval()`	اشتراط موافقة تحمل المعرّف نفسه تمامًا قبل التنفيذ المحلي.
`define_tool(tool)`	إعادة `Tool` المقدّمة للحفاظ على أسلوب موحّد للتعريف.

توقيع المنفّذ هو:

Fn(
    serde_json::Value,
    &RuntimeContext,
) -> Result<serde_json::Value, AgentError>
    + Send
    + Sync
    + 'static

يكشف Tool الحقول id وdescription وparameters وexecute وrequire_approval. فضّل استخدام البُناة وطريقة builder للحفاظ على اتساق أنواع المنفّذات والقيم الافتراضية. يحتوي RuntimeContext الذي يُمرّر إلى المنفّذ على:

run_id
agent_id
step_index
context
tool_call

الرسائل واستدعاءات الأدوات

يحتوي Message على role وcontent وtool_calls وtool_call_id اختياري وname اختياري وis_error. أنشئ الرسائل العادية باستخدام:

Message::user(content)
Message::assistant(content)

يحتوي ToolCall على معرّف الاستدعاء id واسم الأداة name ومدخل JSON input. يحتوي ToolSpec على معرّف الأداة id ووصفها description ومعلمات JSON Schema parameters المرسلة إلى عميل النموذج.

عملاء النماذج

نفّذ ModelClient لاستخدام وسيلة نقل أخرى للنموذج:

pub trait ModelClient {
    fn generate(
        &mut self,
        request: &ModelRequest,
    ) -> Result<ModelResponse, AgentError>;
}

يتوفر محوّل Gateway المضمّن عبر:

GatewayAgentClient::new(phaseo_client, model)
GatewayAgentClient::from_env(model)
create_gateway_agent_client(model)

يرسل المحوّل قيم ModelRequest إلى POST /responses، ويوحّد نص المخرجات واستدعاءات الوظائف وبيانات الطلب الوصفية والاستخدام. يحتوي ModelRequest على معرّف الوكيل والنموذج الفعلي والتعليمات والرسائل الحالية ومواصفات الأدوات وسياق التطبيق. يحتوي ModelResponse على:

message: Message
usage: UsageSummary
request_id: Option<String>
provider: Option<String>
model: Option<String>
finish_reason: Option<String>

أنواع المراجعة والإيقاف المؤقت

يحتوي HumanReviewContext على معرّفي الجولة والوكيل وفهرس الخطوة والرسائل الحالية واستجابة النموذج الموحّدة وسياق التطبيق. أعِد HumanReviewRequest { reason, payload } من callback المراجعة لإيقاف الجولة مؤقتًا. يحتوي HumanPause على:

reason
حمولة JSON payload
kind
pending_tool_calls

يحتوي كل PendingToolCall على ToolCall الأصلي ونوع الإدخال المطلوب kind وسبب مكتوب بلغة واضحة. يوفّر ToolDecision معرّف tool_call_id الموافق عليه وسببًا اختياريًا. ويوفّر ToolOutput معرّف tool_call_id ومخرجات JSON.

سجلات الجولات

يحتوي RunResult على:

run: RunRecord
steps: Vec<RunStep>
output: Value
messages: Vec<Message>
usage: UsageSummary

يحتوي RunRecord على معرّفي الجولة والوكيل والنموذج الفعلي وحد الخطوات والحالة والمدخل الأصلي وسياق التطبيق وعدد الخطوات وإيقاف مؤقت اختياري وسبب توقف اختياري وطوابع زمنية. يحتوي RunStep على الفهرس والحالة وعدد محاولات النموذج واستدعاءات الأدوات ومعرّف الطلب والمزوّد والنموذج وسبب الإنهاء وخطأ اختياري والاستخدام. يحتوي UsageSummary على input_tokens وoutput_tokens وcached_tokens وtotal_tokens وcost. يوفّر عميل النموذج قيمة cost. ولا يربط محوّل Gateway 0.1 المضمّن حاليًا قيم cost_nanos أو cost_cents من Gateway بهذا الحقل. تدعم الأنواع RunResult وRunRecord وRunStep وMessage وToolCall وHumanPause وPendingToolCall وToolDecision وToolOutput وUsageSummary تسلسل Serde عندما تشتق تعريفاتها السمات Serialize وDeserialize.

الأحداث والأخطاء

حقول AgentEvent:

event_type
run_id
agent_id
timestamp_ms
details

ينفّذ AgentError السمات std::error::Error وDisplay. استخدم AgentError::new(...) لإنشاء خطأ، وmessage() لقراءة رسالته.

ابدأ هنا

البناء

الملاحظة

مرجع

مرجع Rust Agent SDK API

تعريف الوكيل

التشغيل والمتابعة

الأدوات

الرسائل واستدعاءات الأدوات

عملاء النماذج

أنواع المراجعة والإيقاف المؤقت

سجلات الجولات

الأحداث والأخطاء

مراجع خارجية

​تعريف الوكيل

​التشغيل والمتابعة

​الأدوات

​الرسائل واستدعاءات الأدوات

​عملاء النماذج

​أنواع المراجعة والإيقاف المؤقت

​سجلات الجولات

​الأحداث والأخطاء

​مراجع خارجية

تعريف الوكيل

التشغيل والمتابعة

الأدوات

الرسائل واستدعاءات الأدوات

عملاء النماذج

أنواع المراجعة والإيقاف المؤقت

سجلات الجولات

الأحداث والأخطاء

مراجع خارجية