Py AI MCP Tool Schemas

MCP工具模式变体

这个回购伴随着谈话 “改进MCP工具模式以提高代理可靠性”. 查看幻灯片

它包含：

• A. FastMCP服务器 为同一费用跟踪操作公开多个工具模式变体

（例如，类别为 str 对比 Literal 对比 Enum 对比 Annotated[Enum]).

• 四种代理实现 （PydanticAI、GitHub Copilot SDK、LangChain、微软代理框架）

它们通过Streamable HTTP连接到MCP服务器。

• 一 评估工具 它跨模式变体运行17个测试用例，并生成比较报告。

目录

• 设置
• 运行MCP服务器
• 运行代理
• 运行评估
• 使用Logfire进行追踪

设置

安装依赖项

uv sync

配置环境变量

创建一个 .env 文件包含：

AZURE_OPENAI_ENDPOINT=https://.openai.azure.com/
AZURE_OPENAI_CHAT_DEPLOYMENT=

您还需要通过以下方式获得Azure凭据 DefaultAzureCredential （奔跑 az login 对于本地开发）， 或设置 AZURE_OPENAI_KEY 用于API密钥身份验证。

可选：

• MCP_SERVER_URL --默认为 http://localhost:8000/mcp
• LOGFIRE_TOKEN --允许将跟踪发送到 篝火

为了使用不同的模型。， .env.gpt4o, .env.gpt53codex) 并将其传递给 --env-file.

运行MCP服务器

uv run python servers/expenses_mcp.py

服务器使用不同的模式方法公开每个工具的多个变体：

• 类别变体 (cat_b 通过 cat_e): Annotated[str], Literal, Enum, Annotated[Enum]
• 日期变体 (date_a 通过 date_d): str, Annotated[str], date, Field(pattern=...)
• 输出变量 (get_expenses_a 通过 get_expenses_c): str, list[dict], list[Expense]

运行代理

首先启动MCP服务器，然后运行任何代理：

PydanticAI

uv run python agents/pydanticai_agent.py
uv run python agents/pydanticai_agent.py --tools add_expense_cat_e --query "Coffee for $5"
uv run python agents/pydanticai_agent.py --reasoning medium --show-tool-calls --show-reasoning

GitHub Copilot 软件开发工具包

uv run python agents/copilotsdk_agent.py
uv run python agents/copilotsdk_agent.py --model gpt-5.3-codex --show-tool-calls

LangChain

uv run python agents/langchain_agent.py
uv run python agents/langchain_agent.py --tools add_expense_cat_c --query "Lunch for $15"

Microsoft代理框架

uv run python agents/agentframework_agent.py
uv run python agents/agentframework_agent.py --tools add_expense_cat_e --reasoning high

常见代理选项

运行评估

评估工具跨模式变体运行一个包含17个提示的数据集，并写入结果 到下的文件夹 撤离/运行/.

# Run all default variants (category + date)
uv run python evals/runner.py --output evals/runs/my_run

# Category variants only
uv run python evals/runner.py --variants add_expense_cat_b,add_expense_cat_c,add_expense_cat_d,add_expense_cat_e \
  --output evals/runs/my_cat_run

# Date variants only
uv run python evals/runner.py --variants add_expense_date_a,add_expense_date_b,add_expense_date_c,add_expense_date_d \
  --output evals/runs/my_date_run

# With a specific model
uv run python evals/runner.py --env-file .env.gpt4o --seed 42 --temperature 0 \
  --output evals/runs/gpt4o_run

# With reasoning (required for gpt-5 level models)
uv run python evals/runner.py --env-file .env.gpt53codex --reasoning medium \
  --output evals/runs/gpt53codex_run

# Output schema evals (get_expenses variants)
uv run python evals/runner.py --eval-type output --output evals/runs/output_run

# With a different agent framework
uv run python evals/runner.py --agent copilot --deployment gpt-5.3-codex \
  --output evals/runs/copilot_run

每次运行都会产生：

• results.json --机器可读的结果，包含每个案例的评估细节
• RESULTS.md --可读摘要报告

使用Logfire进行追踪

MCP服务器和代理都支持 篝火 追踪：

• 集 LOGFIRE_TOKEN 在 .env 启用
• 代理在每次运行后打印Logfire跟踪URL