البدء السريع

أنشئ أول وكيل ذكاء اصطناعي لك في أقل من 5 دقائق.

المتطلبات الأساسية

• Rust 1.95.0 أو إصدار أحدث (rustup update stable)
• مفتاح OpenAI API لهذا الدليل

الخطوة 1: إنشاء هيكل خادم OpenAI

cargo install cargo-adk
cargo adk new quickstart_agent --template api --provider openai
cd quickstart_agent

ينشئ هذا مشروع Rust كاملًا مع وكيل OpenAI، وجلسات مخزنة في الذاكرة، ووقت تشغيل ADK HTTP، ونقاط نهاية للبث، وواجهة مستخدم مضمّنة للتطوير.

القوالب الأخرى

# Agent with custom tools using #[tool] macro
cargo adk new my_agent --template tools

# RAG agent with Gemini embeddings and in-memory vector search
cargo adk new my_agent --template rag

# REST API server with the embedded runtime UI
cargo adk new my_agent --template api

# OpenAI GPT-5-mini agent
cargo adk new my_agent --template openai

# A2A protocol agent with builder API
cargo adk new my_agent --template a2a

# Use any provider with any template
cargo adk new my_agent --template tools --provider anthropic

# Add optional addons to any template
cargo adk new my_agent --template tools --addon docker --addon ci

تلميح: استخدم العلامة --addon لإنشاء قوالب مع إضافات اختيارية مثل docker وci وtelemetry وغير ذلك. راجع صفحة القوالب القابلة للتركيب للاطلاع على القائمة الكاملة التي تضم 9 إضافات و5 أنماط للمؤسسات.

الخطوة 2: أضف مفتاح API الخاص بك

cp .env.example .env
# Open .env and replace the OPENAI_API_KEY placeholder.

يستبعد .gitignore المُنشأ .env. احتفظ بالمفتاح محليًا ولا تُدرجه أبدًا في المستودع.

الخطوة 3: شغّل الوكيل

cargo run

افتح http://127.0.0.1:8080/ui/. سيظهر الوكيل تلقائيًا؛ ولا تحتاج إلى إنشاء جلسة أو استدعاء نقطة نهاية أولًا.

الخطوة 4: اختبره في واجهة مستخدم وقت التشغيل

أدخل مطالبة مثل:

Explain what this agent can do in three concise Markdown bullets.

يتدفق الرد إلى المحادثة. استخدم أداة الفحص الموجودة على اليمين لمراجعة طوبولوجيا التنفيذ، والمخطط الزمني المرتب للأحداث، وتغييرات الحالة، والمصنوعات، والجلسات، وإمكانات البروتوكول، وبيانات القياس عن بُعد دون مغادرة الصفحة.

يستخدم هذا التسجيل عرض الفريق المحمول، لذا يسهل رؤية عملية تسليم المهمة المتحركة. ويستخدم وكيلك المُنشأ من القالب واجهة مستخدم وقت التشغيل نفسها مع طوبولوجيا تتكون من عقدة واحدة.

تحقق من وقت تشغيل HTTP بشكل منفصل إذا أردت إجراء اختبار أولي:

curl -fsS http://127.0.0.1:8080/api/health

لديك الآن ملف تنفيذي واحد يشغّل الوكيل، ويدير الجلسات، ويبث الأحداث، ويقدم واجهة الاختبار الخاصة به. ولا يلزم تثبيت واجهة أمامية منفصلة.

هل تفضّل وكيلًا يعمل من الطرفية فقط؟

استخدم قالب وحدة التحكم OpenAI بدلًا من ذلك:

cargo adk new quickstart_console --template openai
cd quickstart_console
cp .env.example .env   # replace the OPENAI_API_KEY placeholder
cargo run

---

البديل دون إعداد — adk::run()

إذا كنت تريد فقط تشغيل وكيل سريع دون إنشاء هيكل، فاستخدم الأمر في سطر واحد:

use adk_rust::run;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    dotenvy::dotenv().ok();
    // Minimal default: set GOOGLE_API_KEY. Add provider features for OpenAI/Anthropic.
    let response = run("You are a helpful assistant.", "Explain Rust in one sentence.").await?;
    println!("{response}");
    Ok(())
}

يتولى هذا اكتشاف المزوّد للمزوّدين المُترجمين، وإنشاء الجلسة، وبناء الوكيل، والتنفيذ في استدعاء واحد. وهو مناسب للبرامج النصية والنماذج الأولية والتجارب السريعة.

---

فهم الشيفرة المُنشأة

يبني src/main.rs الخاص بـ API كائن LlmAgent عاديًا، ثم يثبّته في الخادم القياسي. التوصيل المهم هو:

use adk_rust::prelude::*;
use adk_rust::server::{ServerConfig, create_app};
use adk_rust::session::InMemorySessionService;
use std::sync::Arc;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    dotenvy::dotenv().ok();
    let api_key = std::env::var("OPENAI_API_KEY")?;

    let model = adk_rust::model::openai::OpenAIClient::new(
        adk_rust::model::openai::OpenAIConfig::new(&api_key, "gpt-5.6-terra"),
    )?;

    let agent: Arc<dyn Agent> = Arc::new(
        LlmAgentBuilder::new("quickstart_agent")
            .description("REST API agent")
            .instruction("You are a helpful assistant accessible via REST API.")
            .model(Arc::new(model))
            .build()?,
    );

    let config = ServerConfig::new(
        Arc::new(adk_rust::SingleAgentLoader::new(agent)),
        Arc::new(InMemorySessionService::new()),
    );
    let app = create_app(config);

    let listener = tokio::net::TcpListener::bind("127.0.0.1:8080").await?;
    axum::serve(listener, app).await?;
    Ok(())
}

---

إضافة أدوات مخصصة

أسرع طريقة لإضافة الأدوات هي استخدام ماكرو #[tool]. أضف adk-tool إلى تبعياتك:

[dependencies]
adk-tool = "2.1.0"
schemars = "1"
serde = { version = "1", features = ["derive"] }

ثم عرّف أداة — حيث يصبح تعليق التوثيق الوصف، ويصبح هيكل الوسائط مخطط JSON:

use adk_tool::{tool, AdkError};
use schemars::JsonSchema;
use serde::Deserialize;
use serde_json::{json, Value};

#[derive(Deserialize, JsonSchema)]
struct WeatherArgs {
    /// The city to look up
    city: String,
}

/// Get the current weather for a city.
#[tool]
async fn get_weather(args: WeatherArgs) -> std::result::Result<Value, AdkError> {
    Ok(json!({ "temp": 22, "city": args.city, "condition": "sunny" }))
}

ينشئ الماكرو بنية GetWeather تطبّق Tool. أضفها إلى وكيلك:

let agent = LlmAgentBuilder::new("weather_agent")
    .instruction("Use the get_weather tool for weather questions.")
    .model(Arc::new(model))
    .tool(Arc::new(GetWeather))  // Generated by #[tool]
    .build()?;

تلميح: أو أنشئ مشروعًا باستخدام قالب يحتوي على الأدوات مُعدّة مسبقًا: cargo adk new my-agent --template tools

الأدوات المضمنة

يتضمن ADK أيضًا أدوات جاهزة للاستخدام:

// Google Search (handled server-side by Gemini)
.tool(Arc::new(GoogleSearchTool::new()))

// Exit a LoopAgent
.tool(Arc::new(ExitLoopTool::new()))

---

التشغيل كخادم ويب

أنشئ مشروع خادم باستخدام قالب عندما تريد تقديم HTTP:

cargo adk new my-api --template api --provider openai
cd my-api
cp .env.example .env
cargo run

افتح http://127.0.0.1:8080/ui/. يستخدم القالب الأساسي الافتراضي مُشغّل وحدة التحكم خفيف الوزن بدلًا من ذلك.

---

استخدام نماذج أخرى

فعّل موفّري الخدمة عبر أعلام الميزات. يظل البناء الافتراضي مقتصرًا على Gemini لتثبيت سريع، لذا أضف موفّر الخدمة الذي تحتاج إليه فقط:

[dependencies]
adk-rust = { version = "2.1.0", features = ["openai"] }

أو أنشئ مشروعًا باستخدام موفّر خدمة: cargo adk new my-agent --provider openai

OpenAI

let api_key = std::env::var("OPENAI_API_KEY")?;
let model = OpenAIClient::new(OpenAIConfig::new(api_key, "gpt-5.6-terra"))?;

Anthropic

let api_key = std::env::var("ANTHROPIC_API_KEY")?;
let model = AnthropicClient::new(AnthropicConfig::new(api_key, "claude-sonnet-5"))?;

DeepSeek

let api_key = std::env::var("DEEPSEEK_API_KEY")?;
let model = DeepSeekClient::chat(api_key)?;         // standard
// let model = DeepSeekClient::reasoner(api_key)?;   // chain-of-thought

Groq

let api_key = std::env::var("GROQ_API_KEY")?;
let model = GroqClient::new(GroqConfig::gpt_oss_120b(api_key))?;

Ollama (محلي)

// Requires: ollama serve && ollama pull llama3.2
let model = OllamaModel::new(OllamaConfig::new("llama3.2"))?;

النماذج المدعومة

---

الخطوات التالية

• LlmAgent Configuration — جميع خيارات التكوين
• أدوات الدوال — إنشاء أدوات مخصصة باستخدام #[tool]
• وكلاء سير العمل — مسارات متسلسلة ومتوازية وحلقية
• الجلسات — إدارة حالة المحادثة
• عمليات الاستدعاء — تخصيص سلوك الوكيل

---

السابق: المقدمة | التالي: LlmAgent