AI导哈

代理AI部署工具

TrueFoundry提供的端到端代理AI系统部署模板，支持通过FastAPI端点或自定义MCP服务器进行企业级部署。

  • by anant173
  • Jupyter Notebook
  • 本地部署
  • 更新于
在 GitHub 查看 anant173/agentic-ai-deployment-cookbook

使用说明

TrueFoundry上的代理式AI：部署指南

这个仓库提供了一个最小化、端到端的模板，用于部署一个功能强大且工具驱动的（系统/应用） 具有主体性的AI系统我们展示了如何封装一个代理工作流（使用 CrewAI（可译为“团队人工智能”或根据具体语境译为更贴切的名称，但在此直接保留原英文形式以体现其专有性） 或者 LangGraph) 通过可扩展的部署方式 TrueFoundry AI网关 通过：

  1. 一个自定义代理在……上 FastAPI 端点以及
  2. 一个定制（品） 模型上下文协议（MCP）服务器 和；与；用 FastMCP

安全注意事项： 我们展示了一个场景 没有MCP服务器认证 为了简化。对于生产环境部署， TrueFoundry（可译为“真代工厂”或根据具体语境译为其他名称，此处保留原英文形式以体现品牌特色） 提供强大的安全功能。请参阅 TrueFoundry MCP网关认证指南 以了解实施细节。

烹饪书步骤

本指南遵循开发单功能代理并将其打包用于企业部署的过程。

1. 开始入门

1a. 代理流程设计（Jupyter Notebook）

代理系统旨在执行 实时研究并整理输出结果以供人类阅读/使用.

我们正在建设一个 双代理研究与报告生成器 这个句子的开头“that uses the”在中文里可能需要根据上下文来完整表达其意思，但仅就“that uses the”本身而言，可以翻译为“使用……的”或“以……为使用的”。不过，这样的翻译比较笼统，具体翻译还需结合后文内容。例如，如果完整句子是“that uses the internet”，那么可以翻译为“使用互联网的” TavilySearchTool 查找最新信息，然后将最终输出格式化为整洁的Markdown字符串（在这个简化版本中，我们不再保存到文件）。

| 代理 | 角色 | 输出 | | 分隔符 | 分隔符 | 分隔符 | | 研究者 | 进行网络搜索并综合搜索结果。| 关于该主题的详细且附有引用的总结。 | | 作家 | 将摘要整理成最终的Markdown报告格式。| 最终的Markdown字符串。|

在笔记本中审查设计并交互式地测试流程：

1b. TrueFoundry 集成代码

您必须正确配置您的大型语言模型（LLM）框架，以确保请求能够通过该框架被正确路由 TrueFoundry AI网关。

选项A：使用CrewAI

# Create an LLM instance with TrueFoundry AI Gateway
from crewai import LLM

truefoundry_llm = LLM(
    api_key="your_truefoundry_api_key",
    base_url="your_truefoundry_gateway_base_url",
    model="openai/openai-main/gpt-4o",  # Format: <provider>/<your-truefoundry-model-id>
)
# This format allows you to call any model (Anthropic, Gemini, etc.) 
# configured on your TrueFoundry Gateway.

选项B：使用LangChain（如果使用LangGraph进行构建）

from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    api_key="your_truefoundry_api_key",
    base_url="your_truefoundry_gateway_base_url/v1",
    model="openai-main/gpt-4o"  # Format: <your-truefoundry-model-id>
)
# This format allows you to call any model (Anthropic, Gemini, etc.) 
# configured on your TrueFoundry Gateway.

1c. Python 环境管理（uv)

我们使用 uv 为了实现超快速、可重复且稳健的依赖管理，您的仓库采用了 pyproject.toml 文件用于声明直接依赖项和一个 uv.lock 锁定整个环境的文件。

要在本地设置您的项目：

命令 用途
uv venv 创建一个独立的Python虚拟环境，通常命名为 .venv。
uv add <package> 安装一个包并 将其添加 到……的 dependencies 列在（列表/清单中） pyproject.toml 以及更新 uv.lock。
uv sync 安装所有依赖项 列于 pyproject.toml 使用其中指定的确切版本 uv.lock 文件，确保完美可重复性。
uv run <script> 在项目的虚拟环境中执行脚本。

1d. 代理代码的Python脚本

最终的代理逻辑被封装成一个可运行的Python脚本，该脚本暴露了核心功能 run_research_analysis(query) FastAPI 端点以及 MCP 服务器所使用的函数。

2. 在FastAPI端点后部署代理

对于传统的RESTful通信，例如提供服务时 网页用户界面（Web UI） 或者与……集成 同步微服务你应该通过标准的 FastAPI 端点来暴露你的代理逻辑。本节详细说明了你的 REST 服务的完整配置。

2a. FastAPI 端点代码

这个脚本定义了应用程序、输入结构以及核心路由逻辑。

2b. 核心组件说明

| 组件 | 代码/逻辑 | 部署中的目的 | | 分隔符 | 分隔符 | 分隔符 | | 进口代理 | from src.{framework}.research_report_generation import run_research_analysis | 唯一的关键区别 在代理框架之间。这导入了核心异步函数。 | | app = FastAPI(...) | 初始化 | 创建 主ASGI应用程序 Uvicorn 服务器将托管该服务。 | | @app.get("/health") | 健康探测器 | 所需的同步端点 TrueFoundry（可译为“真代工厂”或根据具体语境译为更贴切的名称，但直接音译为“特鲁芬德里”或“特鲁弗德里”也可，需结合具体行业或品牌背景确定） 用于容器健康检查（存活性检查）。 | | UserInput(BaseModel) | 输入模式 | 定义了预期的请求体 ({"user_input": "..."}), 提供 验证 并且提供清晰的API文档。 | | @app.post("/run_research_analysis") | 主入口点 | 定义外部网页/REST调用的主要入口点。 | | await run_research_analysis(...) | 执行桥 | 正确地 等待 异步代理函数。这确保了长时间运行的工作流不会阻塞主服务器的事件循环，从而保持服务的响应性。 |

2c. 执行命令

要运行用于网页消费的独立 FastAPI 代理端点：

##Example with LangGraph
uv run uvicorn src.langgraph.agent_fastapi:app --host 0.0.0.0 --port 8000

3. 使用FastMCP部署自定义MCP服务器

3a. 创建MCP服务器

该（或“这个”） mcp_server.py 文件使用了 FastMCP 框架用于转换单一智能体函数（conduct_research_and_report) 转换为网络可访问的工具。

3b. FastMCP 概述

  • 初始化： 这个 FastMCP 对象处理所有协议细节。
    mcp = FastMCP("research_report_generation", stateless_http=True)
  • 工具定义： 我们定义了一个工具，它封装了整个过程。
    @mcp.tool()
def conduct_research_and_report(query: str) -> str:
    # ... calls run_research_analysis(query) ...
    # ... returns final Markdown report ...

3c. FastMCP的关键组件

| 组件 | 用途 | TrueFoundry 上下文 | | 分隔符 | 分隔符 | 分隔符 | | @mcp.tool() | 暴露单一能力： conduct_research_and_report(query)这是由大型语言模型（LLM）客户端（例如Cursor、Claude）执行的功能。 | | @mcp.custom_route("/health") | 创建一个标准的HTTP端点用于健康检查。 | 对部署至关重要。 这可以作为……的 就绪性探针（或存活探针） 监控服务健康状况。 | | 启动配置 | 为内部Uvicorn服务器设置主机和端口。 | 必须监听在 host="0.0.0.0" 和 port=8000 用于TrueFoundry内部的容器化。 |

这个（或：该） mcp_server.py 文件用途 FastMCP 将代理逻辑封装成一个可部署的服务，并添加必要的部署配置。

3d. 执行命令

要运行用于网页消费的独立FastMCP服务器端点：

##Example with LangGraph
uv run src.langgraph.mcp_server.py

3e. 使用MCP Inspector进行本地测试

在部署之前，使用以下方法验证服务器的功能： MCP Inspector（中文可译为“MCP检查器”或根据具体语境调整为更贴切的名称，如“MCP监察系统”等） CLI 工具。此工具允许您直接通过 HTTP 确认服务器的功能并测试工具。

  1. 启动MCP服务器： 在一个终端窗口中运行你的服务器脚本（如果尚未运行的话）：
    uv run src.langgraph.mcp_server.py
  2. 在新终端中测试服务器： 使用 npx 检查功能并调用工具。
    # Inspect the capabilities (tools, resources, prompts)
npx @modelcontextprotocol/inspector

4. 在TrueFoundry上的部署（视频指南）

重要的仅在以下平台注册 https://demo.truefoundry.cloud/（该网址本身不直接翻译，但可表述为）：TrueFoundry 的演示版网站 为黑客马拉松（Hackathon）做准备并（进行/参与） 不是 使用其他租户/URL。

代码完成后，该服务已准备好进行容器化和部署。

最终的部署步骤包括使用TrueFoundry平台将您的代码容器化，并1) 将您的代理部署在FastAPI端点之后，以及2) 部署您的自定义MCP服务器。

4a. 在TrueFoundry上将您的代理部署在FastAPI端点之后（观看时间约3分钟）

观看此指南，了解Agent FastAPI端点的完整部署过程。

4b. 在TrueFoundry上部署您的自定义MCP服务器（观看时间约3分钟）

观看此指南，了解MCP服务器的完整部署过程。

相关 MCP