دليل ترحيل A2A SDK v1

تم تحديث حزم تكامل A2A الخاصة ب Agent Framework لاستخدام A2A SDK v1، مع استبدال التبعية السابقة v0.3. هذا تغيير فاصل يؤثر على كل من حزم A2A Agent (من جانب العميل) وA2A Hosting (من جانب الخادم).

يغطي هذا الدليل التغييرات التي تحتاج إلى إجراؤها لترحيل التعليمات البرمجية الموجودة.

Note

يغطي هذا الدليل التغييرات في طبقة تجريد A2A في إطار العامل.

مرجع سريع

Area	قديم	جديد
تسجيل الخادم	غير مطلوب (تتم معالجته بواسطة `MapA2A`)	`builder.AddA2AServer("agent-name")`
تعيين نقطة النهاية	`app.MapA2A(agent, path, agentCard)` (التحميلات الزائدة المختلفة)	`app.MapA2AHttpJson("agent-name", path)` `app.MapA2AJsonRpc("agent-name", path)`
بطاقة العامل	المعلمة المضمنة في `MapA2A()`	`app.MapWellKnownAgentCard(card)`
خيارات الاستضافة	`A2AHostingOptions`	`A2AServerRegistrationOptions`
تحديد البروتوكول	JSON-RPC فقط، غير قابل للتكوين	يفضل HTTP+JSON، JSON-RPC الاحتياطي. قابل للتكوين عبر `A2AClientOptions.PreferredBindings`

عامل A2A

Package:Microsoft. Agents.AI.A2A

تغييرات توقيع أسلوب المصنع

تقبل أساليب المصنع لإنشاء AIAgent من نقاط نهاية A2A (A2ACardResolver.GetAIAgentAsync()، AgentCard.AsAIAgent()، A2AClient.AsAIAgent()) الآن معلمة اختيارية A2AClientOptions لتكوين سلوك العميل. لم تكن هذه المعلمة موجودة من قبل.

قبل:

AIAgent agent = await resolver.GetAIAgentAsync();

بعد:

A2AClientOptions options = new()
{
    PreferredBindings = [ProtocolBindingNames.HttpJson]
};

AIAgent agent = await resolver.GetAIAgentAsync(options: options);

تحديد البروتوكول

Important

تم تغيير البروتوكول الافتراضي. في السابق، كان عامل A2A يستخدم دائما JSON-RPC (عبر A2AClient). الآن، الافتراضي هو HTTP+JSON مع JSON-RPC كتراجع. إذا كان العامل البعيد يدعم كلا الربطين، فستتحول الطلبات بصمت إلى HTTP+JSON. قم بتعيين A2AClientOptions.PreferredBindings إلى [ProtocolBindingNames.JsonRpc] للحفاظ على السلوك السابق.

يعد تحديد البروتوكول قدرة جديدة.

يمكنك التحكم صراحة في ربط البروتوكول الذي يتم استخدامه عبر A2AClientOptions.PreferredBindings:

A2AClientOptions options = new()
{
    // Explicitly prefer JSON-RPC to maintain previous behavior
    PreferredBindings = [ProtocolBindingNames.JsonRpc]
};

AIAgent agent = await resolver.GetAIAgentAsync(options: options);

Note

يجب أن يدعم عامل A2A البعيد ربط البروتوكول المحدد.

استضافة A2A

الرزم:

Microsoft. Agents.AI.Hosting.A2A - منطق الاستضافة الأساسية (تسجيل الخادم، معالجة الطلب، إدارة الجلسة).
Microsoft. Agents.AI.Hosting.A2A.AspNetCore - ASP.NET Core تعيين نقطة النهاية لروابط بروتوكول A2A. تتضمن هذه الحزمة بشكل عابر الحزمة الأساسية.

تسجيل الخادم

يعد تسجيل خادم A2A الآن خطوة منفصلة وصريحة. في السابق، MapA2A تمت معالجة إعداد الخادم وتعيين نقطة النهاية وبطاقة العامل التي تخدم في مكالمة واحدة. الآن يمكنك تسجيل خادم A2A أثناء تكوين الخدمة وتعيين نقاط النهاية وخدمة بطاقة العامل بشكل منفصل.

قبل:

MapA2A الجمع بين جميع المخاوف الثلاثة. كان لديه تحميل زائد لطرق مختلفة للإشارة إلى العامل، مع اختياري AgentCard ومعلمات Action<ITaskManager> :

// Using an IHostedAgentBuilder
app.MapA2A(agentBuilder, "/a2a/weather-agent");
app.MapA2A(agentBuilder, "/a2a/weather-agent", agentCard);
app.MapA2A(agentBuilder, "/a2a/weather-agent", configureTaskManager);
app.MapA2A(agentBuilder, "/a2a/weather-agent", agentCard, configureTaskManager);

// Using an agent name string
app.MapA2A("weather-agent", "/a2a/weather-agent");
app.MapA2A("weather-agent", "/a2a/weather-agent", agentCard);
app.MapA2A("weather-agent", "/a2a/weather-agent", configureTaskManager);
app.MapA2A("weather-agent", "/a2a/weather-agent", agentCard, configureTaskManager);

// Using an AIAgent instance
app.MapA2A(agent, "/a2a/weather-agent");
app.MapA2A(agent, "/a2a/weather-agent", agentCard);
app.MapA2A(agent, "/a2a/weather-agent", configureTaskManager);
app.MapA2A(agent, "/a2a/weather-agent", agentCard, configureTaskManager);

// Using an ITaskManager directly
app.MapA2A(taskManager, "/a2a/weather-agent");

AIAgent كان للفئة MapA2A أيضا أسلوب ملحق في الحزمة Microsoft.Agents.AI.Hosting.A2A التي أرجعت ITaskManager:

// Using AIAgent extension method
ITaskManager taskManager = agent.MapA2A();
ITaskManager taskManager = agent.MapA2A(agentCard);

Note

ITaskManager لم تعد القيمة المرجعة مكشوفة. استخدم AddA2AServer(agent) بدلا من ذلك؛ يتم حل الأساسي IAgentHandler داخليا بواسطة خادم A2A.

بعد:

أصبح تسجيل الخادم وتعيين نقطة النهاية الآن خطوات منفصلة. AddA2AServer يسجل الخادم، وعين MapA2AHttpJson / MapA2AJsonRpc نقاط النهاية الخاصة بالبروتوكول:

// Using an IHostedAgentBuilder (returned by AddAIAgent)
var agentBuilder = builder.AddAIAgent("weather-agent", instructions: "You are a helpful weather assistant.");
agentBuilder.AddA2AServer();

// Using an agent name string
builder.AddA2AServer("weather-agent");

// Using an AIAgent instance
builder.AddA2AServer(agent);

// Using IServiceCollection directly
builder.Services.AddA2AServer("weather-agent");
builder.Services.AddA2AServer(agent);

للحصول على تفاصيل حول كيفية AddA2AServer العمل وكيفية تجاوز الإعدادات الافتراضية، راجع استضافة A2A.

تعيين نقطة النهاية

يحتوي كل أسلوب تعيين على تحميل زائد ل IHostedAgentBuilderأو AIAgentأو string agentName:

قبل:

app.MapA2A(agentBuilder, path: "/a2a/weather-agent", agentCard: new()
{
    Name = "WeatherAgent",
    Description = "A helpful weather assistant.",
    Version = "1.0"
});

بعد:

// Using an IHostedAgentBuilder
app.MapA2AHttpJson(agentBuilder, "/a2a/weather-agent");  // HTTP+JSON
app.MapA2AJsonRpc(agentBuilder, "/a2a/weather-agent");   // JSON-RPC

// Using an AIAgent instance
app.MapA2AHttpJson(agent, "/a2a/weather-agent");
app.MapA2AJsonRpc(agent, "/a2a/weather-agent");

// Using an agent name string
app.MapA2AHttpJson("weather-agent", "/a2a/weather-agent");
app.MapA2AJsonRpc("weather-agent", "/a2a/weather-agent");

يمكنك تعيين كلا الربطين في وقت واحد بحيث يمكن للعملاء اختيار النقل المفضل لديهم.

بطاقة العامل

تم نقل تكوين بطاقة العامل من معلمة مضمنة إلى MapA2A مكالمة مخصصة. يتم تقديم البطاقة في مسار A2A القياسي المعروف.

قبل:

app.MapA2A(agentBuilder, path: "/a2a/weather-agent", agentCard: new()
{
    Name = "WeatherAgent",
    Description = "A helpful weather assistant.",
    Version = "1.0"
});

بعد:

app.MapWellKnownAgentCard(new AgentCard
{
    Name = "WeatherAgent",
    Description = "A helpful weather assistant.",
    SupportedInterfaces =
    [
        new AgentInterface
        {
            Url = "http://localhost:5000/a2a/weather-agent",
            ProtocolBinding = ProtocolBindingNames.HttpJson,
            ProtocolVersion = "1.0",
        }
    ]
});

Note

MapWellKnownAgentCard يتم توفيرها بواسطة حزمة A2A SDK (A2A.AspNetCore)، وليس حزم استضافة إطار عمل العامل.

Tip

يمكن تقديم بطاقة وكيل واحدة فقط لكل مضيف عبر المسار المعروف. لا يزال من الممكن الوصول إلى الوكلاء الآخرين مباشرة عن طريق عنوان URL. راجع اكتشاف العامل لمزيد من الخيارات.

كامل قبل المثال وبعده

قبل:

using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Hosting;

var builder = WebApplication.CreateBuilder(args);

var weatherAgentBuilder = builder.AddAIAgent("weather-agent",
    instructions: "You are a helpful weather assistant.",
    description: "A helpful weather assistant.");

var app = builder.Build();

app.MapA2A(weatherAgentBuilder, path: "/a2a/weather-agent", agentCard: new()
{
    Name = "WeatherAgent",
    Description = "A helpful weather assistant.",
    Version = "1.0"
});

app.Run();

بعد:

using A2A;
using A2A.AspNetCore;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Hosting;

var builder = WebApplication.CreateBuilder(args);

// 1. Register the agent (unchanged).
var weatherAgentBuilder = builder.AddAIAgent("weather-agent",
    instructions: "You are a helpful weather assistant.",
    description: "A helpful weather assistant.");

// 2. Register the A2A server for the agent.
weatherAgentBuilder.AddA2AServer();

var app = builder.Build();

// 3. Map A2A protocol endpoints.
app.MapA2AHttpJson(weatherAgentBuilder, "/a2a/weather-agent");  // HTTP+JSON
app.MapA2AJsonRpc(weatherAgentBuilder, "/a2a/weather-agent");   // JSON-RPC

// 4. Serve a minimal agent card for discovery.
app.MapWellKnownAgentCard(new AgentCard
{
    Name = "WeatherAgent",
    Description = "A helpful weather assistant.",
    SupportedInterfaces =
    [
        new AgentInterface
        {
            Url = "http://localhost:5000/a2a/weather-agent",
            ProtocolBinding = ProtocolBindingNames.HttpJson,
            ProtocolVersion = "1.0",
        }
    ]
});

app.Run();

واجهات برمجة التطبيقات التي تمت إزالتها وإعادة تسميتها

قديم	جديد
`MapA2A(agent, path, agentCard)`	`AddA2AServer("name")` + `MapA2AHttpJson("name", path)` / `MapA2AJsonRpc("name", path)` + `MapWellKnownAgentCard(card)`
`Microsoft.Agents.AI.Hosting.A2A.AIAgentExtensions.MapA2A`	مدمج في `A2AServerServiceCollectionExtensions.AddA2AServer`
`A2AHostingOptions`	تمت إعادة تسميته إلى `A2AServerRegistrationOptions`

A2A Hosting (من جانب الخادم)

إعداد الخادم

A2AStarletteApplication تمت إزالة فئة الراحة. أنشئ تطبيق Starlette مباشرة باستخدام مساعدي المسار:

قبل:

from a2a.server.apps import A2AStarletteApplication
from a2a.server.request_handlers import DefaultRequestHandler
from a2a.server.tasks import InMemoryTaskStore

request_handler = DefaultRequestHandler(
    agent_executor=A2AExecutor(agent),
    task_store=InMemoryTaskStore(),
)

server = A2AStarletteApplication(
    agent_card=public_agent_card,
    http_handler=request_handler,
).build()

بعد:

from a2a.server.request_handlers import DefaultRequestHandler
from a2a.server.routes import create_agent_card_routes, create_jsonrpc_routes
from a2a.server.tasks import InMemoryTaskStore
from starlette.applications import Starlette

request_handler = DefaultRequestHandler(
    agent_executor=A2AExecutor(agent),
    task_store=InMemoryTaskStore(),
    agent_card=public_agent_card,
)

server = Starlette(
    routes=[
        *create_agent_card_routes(public_agent_card),
        *create_jsonrpc_routes(request_handler, "/"),
    ]
)

Important

DefaultRequestHandler يتطلب الآن المعلمة agent_card . create_jsonrpc_routes يتطلب وسيطة ثانية rpc_url (عادة "/").

بناء بطاقة الوكيل

AgentCard لم يعد يحتوي على حقل المستوى url الأعلى. استخدم supported_interfaces مع AgentInterface بدلا من ذلك. تم نقل أسماء الحقول من camelCase إلى snake_case.

قبل:

from a2a.types import AgentCapabilities, AgentCard, AgentSkill

agent_card = AgentCard(
    name="Travel Agent",
    description="Helps plan travel.",
    url="http://localhost:9999/",
    version="1.0.0",
    defaultInputModes=["text"],
    defaultOutputModes=["text"],
    capabilities=AgentCapabilities(streaming=True),
    skills=[...],
)

بعد:

from a2a.types import AgentCapabilities, AgentCard, AgentInterface, AgentSkill

agent_card = AgentCard(
    name="Travel Agent",
    description="Helps plan travel.",
    version="1.0.0",
    default_input_modes=["text"],
    default_output_modes=["text"],
    capabilities=AgentCapabilities(streaming=True),
    supported_interfaces=[
        AgentInterface(url="http://localhost:9999/", protocol_binding="JSONRPC"),
    ],
    skills=[...],
)

كامل قبل المثال وبعده

قبل:

import uvicorn
from a2a.server.apps import A2AStarletteApplication
from a2a.server.request_handlers import DefaultRequestHandler
from a2a.server.tasks import InMemoryTaskStore
from a2a.types import AgentCapabilities, AgentCard
from agent_framework import Agent
from agent_framework.a2a import A2AExecutor
from agent_framework.openai import OpenAIChatClient

agent_card = AgentCard(
    name="My Agent",
    url="http://localhost:9999/",
    version="1.0.0",
    defaultInputModes=["text"],
    defaultOutputModes=["text"],
    capabilities=AgentCapabilities(streaming=True),
    skills=[],
)

agent = Agent(
    client=OpenAIChatClient(),
    name="My Agent",
    instructions="You are a helpful assistant.",
)

handler = DefaultRequestHandler(
    agent_executor=A2AExecutor(agent),
    task_store=InMemoryTaskStore(),
)

server = A2AStarletteApplication(
    agent_card=agent_card,
    http_handler=handler,
).build()

uvicorn.run(server, host="0.0.0.0", port=9999)

بعد:

import uvicorn
from a2a.server.request_handlers import DefaultRequestHandler
from a2a.server.routes import create_agent_card_routes, create_jsonrpc_routes
from a2a.server.tasks import InMemoryTaskStore
from a2a.types import AgentCapabilities, AgentCard, AgentInterface
from agent_framework import Agent
from agent_framework.a2a import A2AExecutor
from agent_framework.openai import OpenAIChatClient
from starlette.applications import Starlette

agent_card = AgentCard(
    name="My Agent",
    version="1.0.0",
    default_input_modes=["text"],
    default_output_modes=["text"],
    capabilities=AgentCapabilities(streaming=True),
    supported_interfaces=[
        AgentInterface(url="http://localhost:9999/", protocol_binding="JSONRPC"),
    ],
    skills=[],
)

agent = Agent(
    client=OpenAIChatClient(),
    name="My Agent",
    instructions="You are a helpful assistant.",
)

handler = DefaultRequestHandler(
    agent_executor=A2AExecutor(agent),
    task_store=InMemoryTaskStore(),
    agent_card=agent_card,
)

server = Starlette(
    routes=[
        *create_agent_card_routes(agent_card),
        *create_jsonrpc_routes(handler, "/"),
    ]
)

uvicorn.run(server, host="0.0.0.0", port=9999)

واجهات برمجة التطبيقات التي تمت إزالتها وإعادة تسميتها

قديم	جديد
`A2AStarletteApplication`	تمت إزالتها. استخدام `Starlette` من `starlette.applications` مع `create_agent_card_routes` و `create_jsonrpc_routes`
`from a2a.server.apps import A2AStarletteApplication`	`from starlette.applications import Starlette` + `from a2a.server.routes import create_agent_card_routes, create_jsonrpc_routes`
`DefaultRequestHandler(agent_executor=..., task_store=...)`	`DefaultRequestHandler(agent_executor=..., task_store=..., agent_card=...)`
`AgentCard(url=...)`	`AgentCard(supported_interfaces=[AgentInterface(url=..., protocol_binding="JSONRPC")])`
`defaultInputModes` / `defaultOutputModes`	`default_input_modes` / `default_output_modes`
`TextPart`، `FilePart`، `DataPart`	`Part` (مع `text`، `url`، حقول `raw` )
`TaskState.completed`، `TaskState.failed`	`TaskState.TASK_STATE_COMPLETED`، `TaskState.TASK_STATE_FAILED`
`Role("agent")`، `Role("user")`	`Role.ROLE_AGENT`، `Role.ROLE_USER`
`client.resubscribe(...)`	`client.subscribe(...)`

Note

ينطبق دليل الترحيل هذا على حزم C# وحزم Python Agent Framework A2A. لعملاء Go A2A، راجع خدمة عامل A2A؛ لخوادم Go، راجع استضافة A2A.

(راجع أيضًا)

خدمة عامل A2A - مرجع كامل لاستهلاك عوامل A2A البعيدة
استضافة A2A - كشف عوامل إطار عمل العامل من خلال A2A
A2A Hosting - مرجع كامل لواجهة برمجة تطبيقات الاستضافة الجديدة
مواصفات بروتوكول A2A

الملاحظات

هل كانت هذه الصفحة مفيدة؟

Last updated on 2026-08-25

دليل ترحيل A2A SDK v1

مرجع سريع

عامل A2A

تغييرات توقيع أسلوب المصنع

تحديد البروتوكول

استضافة A2A

تسجيل الخادم

تعيين نقطة النهاية

بطاقة العامل

كامل قبل المثال وبعده

واجهات برمجة التطبيقات التي تمت إزالتها وإعادة تسميتها

A2A Hosting (من جانب الخادم)

إعداد الخادم

بناء بطاقة الوكيل

كامل قبل المثال وبعده

واجهات برمجة التطبيقات التي تمت إزالتها وإعادة تسميتها

(راجع أيضًا)

الملاحظات

الموارد الإضافية