AI导哈

产品内代理示例

该示例展示如何在应用内构建一个能够回答订阅计划、团队成员和产品文档问题的代理，结合了GPT-5.1推理模型、Kapa MCP检索工具和自定义工具。

  • by kapa-ai
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 kapa-ai/langchain-agent-example

使用说明

产品代理示例

此仓库包含product-agent中的一个示例，其目的是向您展示如何在应用程序中构建自己的助手。

本例中的代理可以回答有关订阅计划、团队成员和产品文档的问题，但这些都是 虚拟工具它们的存在只是为了展示这种模式；在实际设置中，您可以用调用自己的API和数据存储的工具来替换它们。

真正重要的是方法：

  • 一 推理模型 （GPT-5.1）决定做什么，
  • 本机工具 与您的产品对话（例如计费、团队、设置），
  • 一 通过MCP的Kapa检索工具 它可以搜索您的文档和指南。

这为您提供了一个产品内代理，可以使用您的实时产品数据和文档来帮助用户，而无需离开您的应用程序。

此示例使用LangChain的 create_agent 用于编排和OpenAI推理模型，但您可以将其替换为任何代理框架，包括无代理框架和任何支持工具的推理模型。

先决条件

  • Docker和Docker Compose
  • 一个OpenAI API密钥
  • 一个活动的Kapa帐户，其项目已配置托管MCP服务器（如果您还没有，请按照以下说明操作）

设置您的Kapa MCP服务器

  1. 在 Kapa平台，单击 集成 > +添加新集成
  2. 选择 托管MCP服务器
  3. 配置：
    • 子域：这将成为 <subdomain>.mcp.kapa.ai
    • 服务器名称：MCP服务器标签
    • 认证类型：选择 API密钥 用于产品内代理商
  4. 从集成设置中复制API密钥

重要：产品内代理需要API密钥身份验证。永远不要在客户端代码中公开您的API密钥。

Docker快速入门

  1. 克隆此存储库：
git clone https://github.com/kapa-ai/langchain-agent-example.git
cd langchain-agent-example
  1. 创建您的 .env 使用您的凭据文件：
cp env.example .env

编辑 .env 与你的价值观：

OPENAI_API_KEY=sk-your-openai-api-key
KAPA_MCP_SERVER_URL=https://your-project.mcp.kapa.ai
KAPA_API_KEY=your-kapa-api-key
PRODUCT_NAME=My Awesome Product
  1. 在容器中启动一个shell：
docker compose run --rm agent
  1. 在容器内，运行代理：
python main.py

替代方案：本地Python设置

如果你更喜欢在没有Docker的情况下运行：

  1. 创建虚拟环境：
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
  1. 安装依赖项：
pip install -r requirements.txt
  1. 设置环境变量：
export OPENAI_API_KEY=sk-your-openai-api-key
export KAPA_MCP_SERVER_URL=https://your-project.mcp.kapa.ai
export KAPA_API_KEY=your-kapa-api-key
export PRODUCT_NAME="My Awesome Product"  # Optional
  1. 运行演示：
python main.py

这将启动一个交互式聊天会话，您可以在其中提问。

示例会话

============================================================
  My Awesome Product Assistant
============================================================

Initializing agent...

Loaded 1 tool(s) from Kapa MCP server:
  → search_my_awesome_product_knowledge_sources

👋 Hi! I'm your My Awesome Product assistant. I can help you with:

  📊 Subscription & Billing
     Ask about your plan, seats, features, or renewal dates

  👥 Team Management
     See who's on your team, their roles, and departments

  📚 Product Questions
     How-to guides, features, troubleshooting, and best practices

------------------------------------------------------------
Type 'quit' to exit
------------------------------------------------------------

You: What plan am I on?

🧠 The user is asking about their subscription...

🔧 Calling tool: get_subscription_info
✓ Tool completed

You're on the **Pro** plan with 8/10 seats used.

You: How do I set up webhooks?

🧠 This is a product question, I should search the documentation...

🔧 Calling tool: search_my_awesome_product_knowledge_sources
   query: how to set up webhooks
✓ Tool completed

To set up webhooks, go to Settings → Integrations → Webhooks...

You: What's my plan and who are the admins on my team?

🧠 The user is asking two things - subscription info and team members filtered by role...

🔧 Calling tool: get_subscription_info
✓ Tool completed

🧠 Now I need to get the admin team members...

🔧 Calling tool: get_team_members
   role: admin
✓ Tool completed

You're on the **Pro** plan with 8/10 seats used. Your team has 2 admins:
- Alice Smith (alice.s@acme.com) - Engineering
- Diana Ross (diana.r@acme.com) - Product

项目结构

langchain-agent-example/
├── Dockerfile              # Container image definition
├── docker-compose.yml      # Docker Compose configuration
├── env.example             # Environment variable template
├── main.py                 # Entry point with interactive demo
├── requirements.txt        # Python dependencies
└── src/
    ├── __init__.py
    ├── agent.py           # LangChain agent definition (using create_agent)
    └── tools/
        ├── __init__.py
        ├── subscription.py # Mock subscription info tool
        └── team.py        # Mock team members tool

运作原理

1.代理架构

该代理是使用LangChain的 create_agent 函数，它提供了一种简化的方法来实现ReAct（推理+代理）循环：

from langchain.agents import create_agent
from langchain_openai import ChatOpenAI

# ... (tools and system_prompt defined)

model = ChatOpenAI(
    model="gpt-5.1",
    reasoning={"effort": "medium", "summary": "detailed"},
)

agent = create_agent(
    model=model,
    tools=tools,
    system_prompt=system_prompt,
)

代理人遵循 ReAct（推理+表演）循环:

  1. 理由 --分析情况并决定下一步做什么
  2. 法案 --调用一个或多个工具
  3. 观察 --查看结果
  4. 重复 --如果需要更多信息，请返回步骤1
  5. 回应 --满意后生成最终答案

这个循环是灵活的：代理可以调用一个工具并立即响应，也可以将多个工具调用链接起来，中间有推理步骤。它根据从每个工具结果中学习到的内容动态地做出决定。

2.Kapa MCP集成

Kapa托管MCP服务器集成为一个工具，使用 langchain-mcp-adapters。这允许代理商访问您的产品文档：

from langchain_mcp_adapters.client import MultiServerMCPClient

mcp_client = MultiServerMCPClient({
    "kapa": {
        "transport": "streamable_http",
        "url": "https://your-project.mcp.kapa.ai",
        "headers": {
            "Authorization": f"Bearer {api_key}"
        }
    }
})

# Get tools from MCP server (e.g., search_yourproduct_knowledge_sources)
mcp_tools = await mcp_client.get_tools()

3.自定义工具

内部工具（如 get_subscription_info 和 get_team_members)使用LangChain的 @tool 装饰师。这些代表与产品内部API或数据库的交互。

from langchain_core.tools import tool

@tool
def get_subscription_info(user_id: str = None) -> str:
    """Get information about the user's subscription plan."""
    # In production: call your billing API
    return "Mock subscription data"

了解更多

相关 MCP