企业官网建设流程全解析

pyton 网站开发,长沙房价2021新楼盘价格,建模e-r跟做网站有什么关系,苏州百度seo关键词优化在本教程中#xff0c;你将使用 Python SDK 探索一个简单的“回显”#xff08;echo#xff1a;就是直接返回一个固定的字符串#xff09;A2A 服务器。这将帮助你了解 A2A 服务器的基本概念和核心组件。 本教程分为以下步骤#xff1a; 环境设置#xff08;Setup#xf…在本教程中你将使用 Python SDK 探索一个简单的“回显”echo就是直接返回一个固定的字符串A2A 服务器。这将帮助你了解 A2A 服务器的基本概念和核心组件。本教程分为以下步骤环境设置Setup准备你的 Python 环境及 A2A SDK。智能体技能与智能体卡片Agent Skills Agent Card定义你的智能体能做什么以及它如何描述自身。智能体执行器The Agent Executor理解智能体逻辑是如何实现的。启动服务器Starting the Server运行 Helloworld A2A 服务器。与服务器交互Interacting with the Server向你的智能体发送请求。环境设置Setup要求Python 3.10 或更高版本这里默认你已经会配置Python相关环境了pipinstalla2a-sdk我测试的版本是0.3.16智能体技能Agent Skills与智能体卡片Agent Card在 A2A 智能体能够执行任何操作之前它必须先明确两件事它能做什么即它的技能Skills其他智能体或客户端如何了解这些能力即通过它的智能体卡片Agent Card。上面这两句话已经把Agent Skills和Agent Card概况的非常准确了。核心是Agent Card这个需要给外部调用而Agent Skills仅仅是Agent Card的一个组成部分把它单独出来是为了更加明了的定义该智能体能做什么。智能体技能Agent Skills智能体技能Agent Skill 描述了该智能体所能执行的某项具体能力或功能。它是客户端理解“这个智能体能处理哪些任务”的基本构建单元。在 a2a.types 中定义的 AgentSkill 包含以下关键属性id该技能的唯一标识符。name人类可读的技能名称。description对该技能功能的更详细说明。tags用于分类和发现的关键词标签。examples示例提示prompts或使用场景。inputModes / outputModes支持的输入和输出媒体类型Media Types例如 “text/plain” 或 “application/json”。所以一个Helloworld 智能体的技能很简单skillAgentSkill(idhello_world,nameReturns hello world,descriptionjust returns hello world,tags[hello world],examples[hi,hello world],)这个技能非常简单它的名称是 “Returns hello world”主要处理纯文本输入并原样返回固定响应。智能体卡片Agent Card智能体卡片Agent Card 是一个 JSON 文档由 A2A 服务器对外提供通常可通过 .well-known/agent-card.json 端点访问。你可以把它看作是该智能体的“数字名片”。在 a2a.types 中定义的 AgentCard 包含以下关键属性name, description, version智能体的基本身份信息。urlA2A 服务的访问端点地址。capabilities声明该智能体支持的 A2A 高级特性例如流式传输streaming或推送通知pushNotifications。defaultInputModes / defaultOutputModes该智能体默认支持的输入和输出的类型比如text。skills该智能体提供的 AgentSkill 对象列表。一个HelloWorld智能体卡片定义如下# 这将是对外公开的智能体卡片public_agent_cardAgentCard(nameHello World Agent,descriptionJust a hello world agent,urlhttp://localhost:9999/,version1.0.0,default_input_modes[text],default_output_modes[text],capabilitiesAgentCapabilities(streamingTrue),skills[skill],# 公开卡片中仅包含基础技能supports_authenticated_extended_cardTrue,)这张卡片告诉我们智能体名为 “Hello World Agent”运行在 http://localhost:9999/支持纯文本text的输入与输出提供 hello_world 技能同时声明支持流式响应streamingTrue并且支持通过认证获取扩展版智能体卡片supports_authenticated_extended_cardTrue但公开版本无需凭证即可访问。理解 智能体卡片 至关重要因为它是客户端发现智能体并学习如何与其交互的主要方式。当一个客户端想要调用某个 A2A 智能体时它首先会获取该智能体的 Agent Card从中解析出可用技能、通信格式、端点地址等信息从而发起正确的请求。智能体执行器The Agent ExecutorA2A 智能体如何处理请求并生成响应或事件的核心逻辑由 智能体执行器Agent Executor 负责。A2A Python SDK 提供了一个抽象基类 a2a.server.agent_execution.AgentExecutor你需要继承并实现它。AgentExecutor 接口AgentExecutor InterfaceAgentExecutor 类定义了两个主要方法async def execute(self, context: RequestContext, event_queue: EventQueue)处理传入的请求无论是期望单次响应还是事件流。它通过 context 获取用户输入并使用 event_queue 向客户端发送以下类型的事件对象Message消息Task任务TaskStatusUpdateEvent任务状态更新事件TaskArtifactUpdateEvent任务产物更新事件async def cancel(self, context: RequestContext, event_queue: EventQueue)处理取消正在进行的任务的请求。其中RequestContext 提供了关于当前请求的信息例如用户的输入消息、已有任务的详细信息等。EventQueue 是执行器用来将结果或中间事件异步发送回客户端的通道。Helloworld 智能体执行器Helloworld Agent Executor智能体HelloWorldAgent这是一个简单的辅助类封装了实际的“业务逻辑”classHelloWorldAgent:Hello World Agent.asyncdefinvoke(self)-str:returnHello World它只有一个 invoke 方法异步返回字符串 “Hello World”。执行器HelloWorldAgentExecutor该类实现了 AgentExecutor 接口。初始化initclassHelloWorldAgentExecutor(AgentExecutor):Test AgentProxy Implementation.def__init__(self):self.agentHelloWorldAgent()在初始化时它创建了一个 HelloWorldAgent 实例。执行方法executeasyncdefexecute(self,context:RequestContext,event_queue:EventQueue,)-None:resultawaitself.agent.invoke()awaitevent_queue.enqueue_event(new_agent_text_message(result))当收到 message/send 或 message/stream 请求时在这个简化版执行器中两者均由 execute 处理调用 self.agent.invoke() 获取 “Hello World” 字符串使用工具函数 new_agent_text_message 创建一个符合 A2A 协议的 Message 对象将该消息放入 event_queue 中。底层的 DefaultRequestHandler 会消费这个队列并将事件发送给客户端对于 message/send这将作为一次性完整响应返回对于 message/stream这将作为一个单独的事件发出随后流即关闭因为只有一条消息。取消方法cancelHelloworld 示例中的 cancel 方法直接抛出异常表明这个基础智能体不支持任务取消asyncdefcancel(self,context:RequestContext,event_queue:EventQueue)-None:raiseException(cancel not supported)AgentExecutor 充当了 A2A 协议层由请求处理器和服务器应用管理与你自定义智能体逻辑之间的桥梁。它接收包含用户请求上下文的 RequestContext并通过 EventQueue 将执行结果或中间状态以标准 A2A 事件的形式返回给客户端。这种设计使得智能体逻辑与协议通信解耦便于扩展和维护。启动服务器Starting the Server现在我们已经有了 智能体卡片Agent Card 和 智能体执行器Agent Executor就可以配置并启动 A2A 服务器了。A2A Python SDK 提供了一个名为 A2AStarletteApplication 的类用于简化符合 A2A 规范的 HTTP 服务器的搭建。该类基于 Starlette Web 框架构建通常使用 ASGI 服务器如 Uvicorn运行。Helloworld 示例中的服务器配置下面代码是服务器如何初始化和启动importuvicornfroma2a.server.appsimportA2AStarletteApplicationfroma2a.server.request_handlersimportDefaultRequestHandlerfroma2a.server.tasksimportInMemoryTaskStorefroma2a.typesimport(AgentCapabilities,AgentCard,AgentSkill,)fromagent_executorimport(HelloWorldAgentExecutor,# type: ignore[import-untyped])if__name____main__:skillAgentSkill(idhello_world,nameReturns hello world,descriptionjust returns hello world,tags[hello world],examples[hi,hello world],)extended_skillAgentSkill(idsuper_hello_world,nameReturns a SUPER Hello World,descriptionA more enthusiastic greeting, only for authenticated users.,tags[hello world,super,extended],examples[super hi,give me a super hello],)# 这是对外公开的智能体卡片public_agent_cardAgentCard(nameHello World Agent,descriptionJust a hello world agent,urlhttp://localhost:9999/,version1.0.0,default_input_modes[text],default_output_modes[text],capabilitiesAgentCapabilities(streamingTrue),skills[skill],# 公开卡片仅包含基础技能supports_authenticated_extended_cardTrue,)# 这是经过认证后可访问的扩展版智能体卡片# 包含额外的 extended_skillspecific_extended_agent_cardpublic_agent_card.model_copy(update{name:Hello World Agent - Extended Edition,# 为清晰起见使用不同名称description:The full-featured hello world agent for authenticated users.,version:1.0.1,# 甚至可以是不同版本# capabilities、url、default_input_modes 等字段若未在此指定# 则从 public_agent_card 继承skills:[skill,extended_skill,],# 扩展卡片包含两个技能})request_handlerDefaultRequestHandler(agent_executorHelloWorldAgentExecutor(),task_storeInMemoryTaskStore(),)serverA2AStarletteApplication(agent_cardpublic_agent_card,http_handlerrequest_handler,extended_agent_cardspecific_extended_agent_card,)uvicorn.run(server.build(),host0.0.0.0,port9999)代码解析DefaultRequestHandlerSDK 提供的 DefaultRequestHandler 负责将 A2A 协议的 RPC 调用路由到你的执行器方法如 execute 或 cancel。它接收你实现的 AgentExecutor此处为 HelloWorldAgentExecutor同时需要一个 TaskStore此处使用内存型的 InMemoryTaskStore。TaskStore 的作用管理任务的生命周期尤其在支持状态保持、流式响应或多轮交互时至关重要。即使你的执行器逻辑很简单请求处理器仍需要一个 TaskStore 实例。A2AStarletteApplication该类用于构建完整的 A2A 服务器应用agent_card传入公开的智能体卡片。服务器会自动将其暴露在默认端点 /.well-known/agent-card.json 上。http_handler即 request_handler负责处理所有传入的 A2A 方法调用并与你的 AgentExecutor 交互。extended_agent_card可选如果设置了 supports_authenticated_extended_cardTrue则可通过认证获取此扩展卡片包含更多技能或能力。uvicorn.run(…)A2AStarletteApplication 的 build() 方法会生成一个标准的 Starlette 应用使用 uvicorn.run() 启动该应用使其通过 HTTP 对外提供服务host‘0.0.0.0’ 表示监听所有网络接口不仅限于本地回环port9999 指定监听端口必须与 AgentCard 中的 url 字段一致此处为 http://localhost:9999/。运行 Helloworld 服务器在终端中进入 a2a-samples 目录如果尚未进入并确保已激活虚拟环境。运行以下命令启动 Helloworld 服务器# 从 a2a-samples 目录执行python samples/python/agents/helloworld/__main__.py你应该会看到类似以下的输出表明服务器已成功启动INFO: Started server process [xxxxx] INFO: Waiting for application startup. INFO: Application startup complete. INFO: Uvicorn running on http://0.0.0.0:9999 (Press CTRLC to quit)现在你的 A2A Helloworld 智能体已上线并开始监听来自客户端的请求与服务器交互Interacting with the Server现在 Helloworld A2A 服务器正在运行让我们向它发送一些请求。SDK 提供了一个客户端类 A2AClient可简化这些交互操作。Helloworld 测试客户端The Helloworld Test Client客户端代码的功能从服务器获取智能体卡片Agent Card创建一个 A2AClient 实例发送非流式请求message/send和流式请求message/stream。客户端代码解析Understanding the Client Code获取智能体卡片并初始化客户端base_urlhttp://localhost:9999asyncwithhttpx.AsyncClient()ashttpx_client:# 初始化 A2ACardResolverresolverA2ACardResolver(httpx_clienthttpx_client,base_urlbase_url,# agent_card_path 使用默认值extended_agent_card_path 也使用默认值)A2ACardResolver 是一个便捷工具类它会自动从服务器的 /.well-known/agent-card.json 端点基于提供的 base_url获取 AgentCard然后可用于初始化 A2AClient。注意在正常开发中resolver 通常还会处理认证以获取扩展卡片但 Helloworld 示例中仅使用公开卡片。发送非流式消息send_messageclientA2AClient(httpx_clienthttpx_client,agent_cardfinal_agent_card_to_use)logger.info(A2AClient initialized.)send_message_payload:dict[str,Any]{message:{role:user,parts:[{kind:text,text:how much is 10 USD in INR?}],messageId:uuid4().hex,},}requestSendMessageRequest(idstr(uuid4()),paramsMessageSendParams(**send_message_payload))responseawaitclient.send_message(request)print(response.model_dump(modejson,exclude_noneTrue))send_message_payload 构造了 MessageSendParams 所需的数据封装为 SendMessageRequest符合 JSON-RPC 2.0 格式消息对象包含role: “user”表示这是用户输入parts: 一个文本片段列表此处只有一段纯文本messageId: 唯一消息 ID使用 UUID 生成。尽管用户发送的是 “10美元兑多少印度卢比”但 Helloworld 智能体的 execute 方法始终返回 “Hello World”。这体现了它作为“回显”示例的本质——不处理实际逻辑仅验证通信流程。服务器的 DefaultRequestHandler 会调用 execute获取 “Hello World” 消息并将其作为响应返回响应类型为 SendMessageResponse其 result 字段包含一个 SendMessageSuccessResponse内含智能体返回的 Message或在出错时返回 JSONRPCErrorResponse。关于任务 ID 的说明Handling Task IDs – Helloworld 特例Helloworld 示例不会直接调用 get_task 或 cancel_task原因如下当通过 message/send 调用 Helloworld 智能体时DefaultRequestHandler 会立即返回一个完整的 Message而不是一个 Task 对象只有在更复杂的智能体中message/send 才可能返回一个 Task其 id 可用于后续查询get_task或取消cancel_task。发送流式消息send_message_streamingstreaming_requestSendStreamingMessageRequest(idstr(uuid4()),paramsMessageSendParams(**send_message_payload))stream_responseclient.send_message_streaming(streaming_request)asyncforchunkinstream_response:print(chunk.model_dump(modejson,exclude_noneTrue))此方法调用智能体的 message/stream 端点DefaultRequestHandler 同样会调用 HelloWorldAgentExecutor.executeexecute 方法将一条 “Hello World” 消息加入事件队列然后关闭队列客户端会收到一个 SendStreamingMessageResponse 事件即一个 chunk随后流结束stream_response 是一个 AsyncGenerator因此使用 async for 遍历。预期输出Expected Output运行客户端代码后你会看到两段 JSON 输出非流式响应单条 “Hello World” 消息{jsonrpc:2.0,id:xxxxxxxx,result:{type:message,role:agent,parts:[{type:text,text:Hello World}],messageId:yyyyyyyy}}流式响应单个 chunk包含 “final”: true 表示流结束{jsonrpc:2.0,id:zzzzzzzz,result:{type:message,role:agent,parts:[{type:text,text:Hello World}],messageId:wwwwwwww,final:true}}完整代码https://github.com/a2aproject/a2a-samples/tree/main/samples