mcp-run-python

<div align="center"> <a href="https://ai.pydantic.dev/"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://ai.pydantic.dev/img/pydantic-ai-dark.svg"> <img src="https://ai.pydantic.dev/img/pydantic-ai-light.svg" alt="PydanticAI"> </picture> </a> </div> <div align="center"> <em>使用 Pydantic 与 LLM 的 Agent 框架 / shim</em> </div> <div align="center"> <a href="https://github.com/pydantic/pydantic-ai/actions/workflows/ci.yml?query=branch%3Amain"><img src="https://github.com/pydantic/pydantic-ai/actions/workflows/ci.yml/badge.svg?event=push" alt="CI"></a> <a href="https://coverage-badge.samuelcolvin.workers.dev/redirect/pydantic/pydantic-ai"><img src="https://coverage-badge.samuelcolvin.workers.dev/pydantic/pydantic-ai.svg" alt="Coverage"></a> <a href="https://pypi.python.org/pypi/pydantic-ai"><img src="https://img.shields.io/pypi/v/pydantic-ai.svg" alt="PyPI"></a> <a href="https://github.com/pydantic/pydantic-ai"><img src="https://img.shields.io/pypi/pyversions/pydantic-ai.svg" alt="versions"></a> <a href="https://github.com/pydantic/pydantic-ai/blob/main/LICENSE"><img src="https://img.shields.io/github/license/pydantic/pydantic-ai.svg?v" alt="license"></a> </div>

---

文档: ai.pydantic.dev

---

PydanticAI 是一个 Python agent 框架，旨在减少使用生成式 AI 构建生产级应用程序的痛苦。

FastAPI 通过提供创新且符合人体工程学的设计，彻底改变了 Web 开发，该设计建立在 Pydantic 的基础上。

同样，Python 中几乎每个 agent 框架和 LLM 库都使用 Pydantic，但当我们开始在 Pydantic Logfire 中使用 LLM 时，我们找不到任何能给我们带来相同感觉的东西。

我们构建 PydanticAI 的目标很简单：将 FastAPI 的感觉带到 GenAI 应用程序开发中。

为什么使用 PydanticAI

• 由 Pydantic 团队构建 由 Pydantic 背后的团队构建（OpenAI SDK、Anthropic SDK、LangChain、LlamaIndex、AutoGPT、Transformers、CrewAI、Instructor 和更多项目的验证层）。

• 模型无关 支持 OpenAI、Anthropic、Gemini、Deepseek、Ollama、Groq、Cohere 和 Mistral，并且有一个简单的接口来实现对 其他模型 的支持。

• Pydantic Logfire 集成 与 Pydantic Logfire 无缝 集成，用于对 LLM 驱动的应用程序进行实时调试、性能监控和行为跟踪。

• 类型安全 旨在使 类型检查 尽可能强大和信息丰富。

• 以 Python 为中心的设计 利用 Python 熟悉的控制流和 agent 组合来构建 AI 驱动的项目，从而可以轻松应用您在任何其他（非 AI）项目中使用的标准 Python 最佳实践。

• 结构化响应 利用 Pydantic 的强大功能来 验证和结构化 模型输出，确保响应在运行之间保持一致。

• 依赖注入系统 提供一个可选的 依赖注入 系统，用于向 agent 的 系统提示、工具 和 结果验证器 提供数据和服务。这对于测试和评估驱动的迭代开发非常有用。

• 流式响应 提供 流式传输 LLM 输出的能力，并进行即时验证，从而确保快速准确的结果。

• 图支持 Pydantic Graph 提供了一种使用类型提示定义图的强大方法，这在标准控制流可能退化为意大利面条式代码的复杂应用程序中非常有用。

Hello World 示例

这是一个 PydanticAI 的最小示例：

from pydantic_ai import Agent

# 定义一个非常简单的 agent，包括要使用的模型，您也可以在运行 agent 时设置模型。
agent = Agent(
    'google-gla:gemini-1.5-flash',
    # 使用关键字参数向 agent 注册静态系统提示。
    # 对于更复杂的动态生成的系统提示，请参见下面的示例。
    system_prompt='Be concise, reply with one sentence.',
)

# 同步运行 agent，与 LLM 进行对话。
# 这里的交换应该非常短：PydanticAI 会将系统提示和用户查询发送到 LLM，
# 模型将返回文本响应。 有关更复杂的运行，请参见下文。
result = agent.run_sync('Where does "hello world" come from?')
print(result.data)
"""
The first known use of "hello, world" was in a 1974 textbook about the C programming language.
"""

(此示例是完整的，可以“按原样”运行)

还不是很吸引人，但是我们可以轻松地添加“工具”、动态系统提示和结构化响应来构建更强大的 agent。

工具和依赖注入示例

这是一个使用 PydanticAI 构建银行支持 agent 的简洁示例：

(更好的文档示例 在文档中)

from dataclasses import dataclass

from pydantic import BaseModel, Field
from pydantic_ai import Agent, RunContext

from bank_database import DatabaseConn


# SupportDependencies 用于将数据、连接和逻辑传递到模型中，这些数据、连接和逻辑在运行系统提示和工具函数时需要。
# 依赖注入提供了一种类型安全的方式来自定义 agent 的行为。
@dataclass
class SupportDependencies:
    customer_id: int
    db: DatabaseConn


# 此 pydantic 模型定义了 agent 返回的结果的结构。
class SupportResult(BaseModel):
    support_advice: str = Field(description='Advice returned to the customer')
    block_card: bool = Field(description="Whether to block the customer's card")
    risk: int = Field(description='Risk level of query', ge=0, le=10)


# 此 agent 将充当银行中的第一层支持。
# Agent 在它们接受的依赖项类型和它们返回的结果类型中是通用的。
# 在这种情况下，支持 agent 的类型为 `Agent[SupportDependencies, SupportResult]`。
support_agent = Agent(
    'openai:gpt-4o',
    deps_type=SupportDependencies,
    # 保证来自 agent 的响应将是 SupportResult，
    # 如果验证失败，则提示 agent 再次尝试。
    result_type=SupportResult,
    system_prompt=(
        'You are a support agent in our bank, give the '
        'customer support and judge the risk level of their query.'
    ),
)


# 动态系统提示可以利用依赖注入。
# 依赖项通过 `RunContext` 参数传递，该参数使用上面的 `deps_type` 进行参数化。
# 如果此处的类型注释错误，则静态类型检查器将捕获它。
@support_agent.system_prompt
async def add_customer_name(ctx: RunContext[SupportDependencies]) -> str:
    customer_name = await ctx.deps.db.customer_name(id=ctx.deps.customer_id)
    return f"The customer's name is {customer_name!r}"


# `tool` 允许您注册 LLM 在响应用户时可能调用的函数。
# 同样，依赖项通过 `RunContext` 传递，任何其他参数都将成为传递给 LLM 的工具模式。
# Pydantic 用于验证这些参数，并且错误会传递回 LLM，以便它可以重试。
@support_agent.tool
async def customer_balance(
    ctx: RunContext[SupportDependencies], include_pending: bool
) -> float:
    """Returns the customer's current account balance."""
    # 工具的文档字符串也作为工具的描述传递给 LLM。
    # 参数描述从文档字符串中提取并添加到发送给 LLM 的参数模式中。
    balance = await ctx.deps.db.customer_balance(
        id=ctx.deps.customer_id,
        include_pending=include_pending,
    )
    return balance


...  # 在实际用例中，您将添加更多工具和更长的系统提示


async def main():
    deps = SupportDependencies(customer_id=123, db=DatabaseConn())
    # 异步运行 agent，与 LLM 进行对话，直到达到最终响应。
    # 即使在这种相当简单的情况下，agent 也会与 LLM 交换多条消息，因为会调用工具来检索结果。
    result = await support_agent.run('What is my balance?', deps=deps)
    # 将使用 Pydantic 验证结果以保证它是 `SupportResult`，因为 agent 是通用的，
    # 它也将被键入为 `SupportResult` 以帮助进行静态类型检查。
    print(result.data)
    """
    support_advice='Hello John, your current account balance, including pending transactions, is $123.45.' block_card=False risk=1
    """

    result = await support_agent.run('I just lost my card!', deps=deps)
    print(result.data)
    """
    support_advice="I'm sorry to hear that, John. We are temporarily blocking your card to prevent unauthorized transactions." block_card=True risk=8
    """

下一步

要亲自尝试 PydanticAI，请按照 示例 中的说明进行操作。

阅读 文档 以了解有关使用 PydanticAI 构建应用程序的更多信息。

阅读 API 参考 以了解 PydanticAI 的接口。