关键词

AI Agent框架Agent部署Agent互操作Agent运行时工具调用

项目简介

Contexa SDK 是一个全面的框架，旨在标准化 AI Agent 的开发、部署和互操作性。它提供了一个统一的抽象层，使得 Agent 的核心组件（工具、模型、Prompt 等）可以在不同 Agent 框架（如 LangChain, CrewAI, OpenAI Agent SDK, Google ADK）之间无缝转换和使用。

作为其核心能力的一部分，Contexa SDK 支持 Model Context Protocol (MCP)，并提供了工具来构建和部署 MCP 兼容的 Agent 服务器，从而允许 Agent 以标准化的方式通过网络对外提供服务。

主要功能点

  • 统一核心对象: 框架无关地定义工具、模型、Agent 和 Prompt。
  • 多框架适配器: 将 Contexa 对象转换为 LangChain, CrewAI, OpenAI, Google ADK 等框架的原生对象。
  • Agent 运行时: 管理 Agent 的生命周期、状态持久化、资源追踪和健康监控（支持本地和模拟集群运行时）。
  • 可观测性: 集成结构化日志、指标和追踪。
  • MCP 集成: 支持构建和消费 MCP 兼容的服务，可以将 Contexa Agent 暴露为 MCP 端点，并允许通过 MCP 协议调用远程 Agent。

安装步骤

使用 pip 安装 Contexa SDK：

pip install contexa-sdk

如果需要特定框架的支持，可以安装对应的额外依赖：

pip install contexa-sdk[langchain]
pip install contexa-sdk[crewai]
pip install contexa-sdk[openai]
pip install contexa-sdk[google-adk]
# 安装所有框架支持
pip install contexa-sdk[all]

MCP 服务器配置 (供MCP客户端参考)

Contexa SDK 允许将您使用 SDK 构建的 Agent 打包成一个独立的 MCP 兼容服务器应用。这个服务器通常被构建成一个 Docker 镜像，并通过 HTTP 协议提供 MCP 服务。

MCP 客户端连接到该服务器时，通常需要以下信息：

  • 服务器名称 (server name): 服务器标识符，例如 'Contexa MCP Agent Server' 或具体的 Agent 名称（如 'Weather Expert'）。
  • 协议 (protocol): 服务器使用的通信协议，对于 Contexa SDK 生成的服务器，通常是 'http' 或 'mcp-http'。
  • 地址 (address): MCP 服务器的网络地址，例如 'http://localhost:8000' (本地运行) 或一个特定的云服务 URL（如 'https://api.contexa.ai/v0/mcp/your-org/your-agent'）。
  • 能力声明 (capabilities): 服务器支持的 MCP 操作，例如 'run' (运行 Agent)、'tools' (获取工具列表)、'metadata' (获取元数据)、'handoff' (处理 Agent 移交)。

请注意： Contexa SDK 生成的 MCP 服务器是基于 HTTP/RESTful API 的，而不是基于 Stdio, SSE 或 WebSocket 传输协议上的 JSON-RPC。如果您使用的 MCP 客户端严格要求 JSON-RPC over Stdio/SSE/WebSocket，可能需要额外的适配层或调整。

典型的 MCP 客户端配置片段示例 (具体格式取决于您的客户端)：

{
  "servers": [
    {
      "server_name": "Example Contexa Agent",
      "description": "A sample agent deployed as an MCP endpoint.",
      "protocol": "http",
      "address": "YOUR_AGENT_ENDPOINT_URL", 
      "capabilities": ["run", "tools", "metadata", "handoff"],
      "auth": { 
          "type": "api_key", 
          "key": "YOUR_API_KEY" 
      }
    }
  ]
}

重要提示: 上述 'address' 应该替换为您实际部署的 MCP Agent 服务器的 URL。认证方式 ('auth') 也取决于您的部署环境和配置。

基本使用方法 (构建与部署MCP服务器)

  1. 定义 Agent: 使用 Contexa SDK 定义您的 'ContexaAgent'，包括其工具、模型和 Prompt。通常在一个 Python 文件中完成 (例如 'my_agent.py')。确保您的文件中定义了一个名为 'contexa_agent' 的变量，指向您的 Agent 实例。

    # my_agent.py
from contexa_sdk.core.agent import ContexaAgent
from contexa_sdk.core.model import ContexaModel
from contexa_sdk.core.tool import ContexaTool
# ... define tools and model ...

my_agent = ContexaAgent(...) 
__contexa_agent__ = my_agent

  2. 构建 MCP 服务器 Artifact: 使用 Contexa CLI 将 Agent 打包成一个 MCP 兼容的服务器 artifact (一个 .tar.gz 文件)。

    ctx build my_agent.py --mcp-compatible --output-dir ./build

    这会在 './build' 目录下生成一个包含 FastAPI 应用、Dockerfile 等文件的压缩包，这是一个可运行的 MCP 服务器代码包。

  3. 部署 MCP 服务器: 使用 Contexa CLI 或标准的 Docker/Kubernetes 流程部署上一步生成的 artifact。如果部署到 Contexa Cloud 或兼容平台，可以使用 'ctx deploy'。

    ctx deploy ./build/my_agent_mcp_1.0_0.1.0.tar.gz

    部署成功后，您将获得一个 MCP 服务器的 HTTP 端点 URL。

  4. MCP 客户端连接: 将上一步获得的 HTTP 端点 URL 配置到您的 MCP 客户端中，即可通过 MCP 协议与您的 Agent 服务器进行交互。例如，使用 Contexa SDK 自身的 'RemoteAgent' 类作为客户端连接：

    import asyncio
from contexa_sdk.core.agent import RemoteAgent

async def connect_and_run():
    mcp_endpoint_url = "YOUR_DEPLOYED_MCP_AGENT_URL" 
    remote_agent = await RemoteAgent.from_endpoint(mcp_endpoint_url)
    response = await remote_agent.run("请问现在天气如何？")
    print(response)

asyncio.run(connect_and_run())

关键词

AI Agent框架, Agent部署, Agent互操作, Agent运行时, 工具调用

信息

分类

AI与计算

访问项目