基于 YAML 的代理

基于 YAML 的代理是在 OpenAgents 中创建由 LLM 驱动的代理的最快方式。在一个简单的配置文件中定义代理的身份、行为和能力，然后通过一条命令运行它。

先决条件

OpenAgents 已安装 (pip install openagents)
一个正在运行的 OpenAgents 网络
一个 LLM API 密钥（例如 OpenAI）

概述

基于 YAML 的代理使用 CollaboratorAgent 类型，提供：

LLM 驱动的响应，使用可配置的模型
具有触发器的事件驱动行为
基于已启用模块的自动工具访问
无需编写代码的简单配置

创建您的第一个 YAML 代理

第 1 步：创建代理文件

创建一个名为 my_agent.yaml 的文件：

type: "openagents.agents.collaborator_agent.CollaboratorAgent"
agent_id: "my-assistant"
 
config:
  model_name: "gpt-4o-mini"
 
  instruction: |
    You are a helpful assistant in an OpenAgents network.
 
    YOUR ROLE:
    - Answer questions clearly and concisely
    - Be friendly and professional
    - Help users understand OpenAgents concepts
 
  react_to_all_messages: true
 
mods:
  - name: "openagents.mods.workspace.messaging"
    enabled: true
 
connection:
  host: "localhost"
  port: 8700
  transport: "grpc"

第 2 步：启动代理

openagents agent start my_agent.yaml

您的代理现在正在运行，并会对网络中的消息作出响应！

配置参考

必填字段

字段	描述
`type`	要使用的代理类（通常是 `CollaboratorAgent`）
`agent_id`	代理的唯一标识符
`config`	代理行为配置
`connection`	网络连接设置

代理配置选项

config:
  # LLM Configuration
  model_name: "gpt-4o-mini"        # Model to use
 
  # Agent Instructions
  instruction: |
    Your system prompt goes here...
 
  # Message Handling
  react_to_all_messages: false     # Respond to all channel messages
 
  # Iteration Limits
  max_iterations: 5                # Max tool calls per response
 
  # Event Triggers (advanced)
  triggers:
    - event: "task.delegate"
      instruction: "Custom handling..."

连接选项

connection:
  host: "localhost"                # Network host
  port: 8700                       # Network port
  transport: "grpc"                # Transport type
  password_hash: "..."             # Optional: for authenticated groups

代理类型与行为

简单聊天代理

响应频道中的所有消息：

type: "openagents.agents.collaborator_agent.CollaboratorAgent"
agent_id: "chat-bot"
 
config:
  model_name: "gpt-4o-mini"
  instruction: |
    You are a friendly chat bot. Respond to all messages with helpful answers.
  react_to_all_messages: true
 
mods:
  - name: "openagents.mods.workspace.messaging"
    enabled: true
 
connection:
  host: "localhost"
  port: 8700
  transport: "grpc"

事件驱动代理

仅对特定事件做出响应：

type: "openagents.agents.collaborator_agent.CollaboratorAgent"
agent_id: "analyst"
 
config:
  model_name: "gpt-4o-mini"
  max_iterations: 3
 
  instruction: |
    You are an analyst. When you receive data, analyze it thoroughly.
 
  react_to_all_messages: false
 
  triggers:
    - event: "task.delegate"
      instruction: |
        Analyze the data in payload.data and send results:
        1. send_event(event_name="task.complete", destination_id="router",
             payload={"results": "your analysis", "status": "success"})
        2. finish()
 
mods:
  - name: "openagents.mods.workspace.project"
    enabled: true
 
connection:
  host: "localhost"
  port: 8700
  transport: "grpc"

具备工具的专用代理

可以访问文件操作的代理：

type: "openagents.agents.collaborator_agent.CollaboratorAgent"
agent_id: "file-manager"
 
config:
  model_name: "gpt-4o-mini"
  instruction: |
    You are a file manager assistant. Help users organize and manage files.
    Use the file tools to list, read, and organize files.
 
mods:
  - name: "openagents.mods.workspace.messaging"
    enabled: true
  - name: "openagents.mods.workspace.files"
    enabled: true
 
connection:
  host: "localhost"
  port: 8700
  transport: "grpc"

使用模组

模组为你的代理提供工具和功能。在 mods 部分启用它们：

常见模组

模组	描述	提供的工具
`messaging`	频道/DM（直接消息）通信	send_channel_message, send_direct_message
`files`	文件操作	list_files, read_file, write_file
`project`	任务管理	create_task, update_task, send_event
`forum`	论坛讨论	create_post, reply_to_post
`default`	基本工作区访问	通用工作区工具

示例：多模组代理

type: "openagents.agents.collaborator_agent.CollaboratorAgent"
agent_id: "super-assistant"
 
config:
  model_name: "gpt-4o-mini"
  instruction: |
    You are a versatile assistant with access to:
    - Channel messaging
    - File management
    - Forum discussions
 
    Use the appropriate tools based on user requests.
 
mods:
  - name: "openagents.mods.workspace.messaging"
    enabled: true
  - name: "openagents.mods.workspace.files"
    enabled: true
  - name: "openagents.mods.workspace.forum"
    enabled: true
 
connection:
  host: "localhost"
  port: 8700
  transport: "grpc"

事件触发器

触发器允许代理对特定事件以自定义行为作出响应：

triggers:
  - event: "task.delegate"           # Event name to listen for
    instruction: |                   # Custom instructions for this event
      When you receive this event, do something specific...
 
  - event: "file.uploaded"
    instruction: |
      A new file was uploaded. Analyze it and report findings...

触发器模式匹配

使用通配符来匹配多个事件：

triggers:
  - event: "task.*"                  # Match task.delegate, task.complete, etc.
    instruction: "Handle any task event..."
 
  - event: "*.error"                 # Match any error event
    instruction: "Handle errors gracefully..."

代理组和认证

对于具有代理组的网络，请包含密码哈希：

connection:
  host: "localhost"
  port: 8700
  transport: "grpc"
  password_hash: "your-password-hash-here"

生成密码哈希：

echo -n "your-password" | sha256sum

运行多个代理

创建多个代理文件并在不同的终端中启动它们：

# Terminal 1
openagents agent start agents/researcher.yaml
 
# Terminal 2
openagents agent start agents/analyst.yaml
 
# Terminal 3
openagents agent start agents/writer.yaml

或者使用一个 shell 脚本：

#!/bin/bash
# start_team.sh
 
openagents agent start agents/researcher.yaml &
openagents agent start agents/analyst.yaml &
openagents agent start agents/writer.yaml &
 
wait

最佳实践

1. 清晰的指示

编写详细且不含歧义的指示：

instruction: |
  You are [ROLE NAME].
 
  YOUR RESPONSIBILITIES:
  - [Specific task 1]
  - [Specific task 2]
 
  RULES:
  - [Important rule 1]
  - [Important rule 2]
 
  OUTPUT FORMAT:
  - [How to structure responses]

2. 防止无限循环

在多代理场景中，注意 react_to_all_messages：

config:
  react_to_all_messages: false     # Prefer event triggers
  max_iterations: 3                # Limit tool calls

3. 使用描述性的代理 ID

# Good
agent_id: "research-coordinator"
agent_id: "customer-support-bot"
 
# Bad
agent_id: "agent1"
agent_id: "bot"

故障排除

代理无法启动

验证 YAML 语法: python -c "import yaml; yaml.safe_load(open('agent.yaml'))"
检查网络是否在运行: curl http://localhost:8700/health
验证 API 密钥是否已设置: echo $OPENAI_API_KEY

代理无响应

检查 react_to_all_messages 设置
确认代理已启用正确的模块
检查代理日志是否有错误

连接错误

确保网络主机/端口与您的网络配置匹配
对于已认证的组，验证 password_hash 是否正确
检查传输类型是否匹配 (http vs grpc)

下一步？

基于 Python 的代理 - 使用自定义 Python 代码构建代理
自定义代理 - 高级代理模式和行为
演示演练 - 查看 YAML 代理的实操演示