光剂
 ](https://github.com/karlyan/light-agent)  
一个灵活而强大的AI代理编排系统，支持多个AI提供商（OpenAI和Claude/Anthropic）。该系统允许您通过YAML配置文件使用共享工具配置和协调多个AI代理。
特性
- 多提供商支持：在同一工作流程中使用OpenAI（GPT-4、GPT-3.5）和Claude（Claude 3 Opus、Sonnet等）代理
- 基于YAML的配置：在简单的YAML文件中定义您的代理、工具和工作流
- 共享工具池：创建一个可以在多个代理之间共享的集中工具池
- MCP服务器支持：与模型上下文协议（MCP）服务器集成，以实现高级工具功能
- 支持多种传输类型： stdio, sse, streamable_http
- 基于文件的提示：从外部文件加载系统提示，以实现更好的组织和可重用性
- 工作流程编排：通过顺序代理协调执行多步骤工作流
- 工作流输出：自动将代理响应保存到文件
- 灵活的代理配置：配置具有不同型号、温度和提供商特定选项的代理
- 嵌套代理：为专门的任务和交接定义嵌套代理
建筑
该系统由五个主要部分组成：
- 配置加载器 (
config_loader.py)：解析YAML配置文件并验证结构 - 工具库 (
tools_pool.py)：管理MCP服务器连接并向代理提供工具 - 提供商系统 (
providers/)：将不同的AI提供商（OpenAI、Claude）抽象到一个通用接口后面 - 代理工厂 (
agent_factory.py)：从配置创建和配置代理实例 - 工作流执行器 (
workflow_executor.py)：跨多个代理协调工作流执行
安装
# Install using uv (recommended)
uv pip install -e .
# Or install dependencies manually
pip install pyyaml openai openai-agents claude-agent-sdk python-dotenv需求
- Python>=3.10
- OpenAI API密钥（用于OpenAI代理）
- Anthropic API密钥（用于Claude代理商）
配置
创建一个YAML配置文件（例如。， configs/sample/agent.yaml):
apiVersion: v1
kind: light-agent
metadata:
name: "k8s-cluster-health-check"
annotations:
description: "Performs comprehensive Kubernetes cluster health checks"
spec:
# Define tools that agents can use
Tools:
- name: shell_mcp_http
description: shell access for LLM
mcp_server:
type: local
command: npx
args:
- "mcp-remote"
- "http://localhost:8080/mcp"
- "--allow-http"
# Define agents with different providers
agents:
k8s_agent_openai:
provider: openai
model: gpt-4
temperature: 1
prompts:
system:
content: |
You are a Kubernetes SRE expert. Analyze logs for root causes,
error patterns, service impact, and remediation steps.
tools:
- name: shell_mcp_http
k8s_agent_claude:
provider: claude
model: claude-sonnet-4-5
temperature: 1
prompts:
system:
content: |
You are a Kubernetes SRE expert with deep system knowledge.
tools:
- name: shell_mcp_http
# Define workflows with outputs
workflows:
steps:
- id: k8s_check_openai
agent: k8s_agent_openai
prompt: |
Check my cluster health and provide a summary.
outputs:
- type: text
destination: outputs/openai_report.txt
- id: k8s_check_claude
agent: k8s_agent_claude
prompt: |
Review the cluster and provide your assessment.
outputs:
- type: text
destination: outputs/claude_report.txt用法
运行系统
# Run with default configuration (uses AGENT_CONFIG_PATH env var or default)
uv run python src/main.py
# Specify configuration file with -c option
uv run python src/main.py -c configs/test/my-config.yaml
# Specify configuration file with --config option
uv run python src/main.py --config /path/to/config.yaml
# Validate configuration file without running the workflow
uv run python src/main.py --validate
uv run python src/main.py -c configs/test/my-config.yaml --validate
# View help information
uv run python src/main.py --help
# Check version
uv run python src/main.py --version正在验证配置
这 --validate 选项允许您检查配置文件是否有效，而无需实际运行工作流或初始化MCP服务器。这有助于：
- 检查YAML语法
- 验证必填字段是否存在
- 验证代理和工具定义
- 检测拼写错误并提出更正建议 ✨
- CI/CD管道中的快速配置测试
# Validate the default configuration
uv run python src/main.py --validate
# Validate a specific configuration file
uv run python src/main.py -c configs/test/my-config.yaml --validate伤寒检测：验证器现在可以检测常见的拼写错误并建议更正：
⚠️ Agent 'test_agent': Unknown field 'temperatur' found. Did you mean: 'temperature'?
⚠️ Workflow step #1: Unknown field 'max_turn' found. Did you mean: 'max_turns'?如果配置有效，您将看到如下摘要：
✓ Configuration file is valid
✓ Agents defined: 2
✓ Tools defined: 1
Tool names: shell_mcp_http
✓ Workflow steps: 2
Step IDs: step1, step2配置优先
系统使用以下优先级顺序选择配置文件：
- 命令行参数 (
-c/--config)-最高优先级 - 环境变量 (
AGENT_CONFIG_PATH) - 默认值 (
configs/sample/agent.yaml)-最低优先级
# Example: Command line overrides environment variable
export AGENT_CONFIG_PATH=configs/default.yaml
uv run python src/main.py -c configs/custom.yaml # Uses configs/custom.yaml控制台脚本
安装软件包后，您可以直接使用CLI：
# Use default configuration
light-agent
# Specify configuration with -c option
light-agent -c configs/sample/agent.yaml
# Specify configuration with --config option
light-agent --config /path/to/config.yaml
# Validate configuration without running
light-agent --validate
light-agent -c configs/test/my-config.yaml --validate
# View help
light-agent --help
# Check version
light-agent --version设置API密钥
创建一个 .env 项目根目录中的文件：
# For OpenAI agents
OPENAI_API_KEY=your-openai-api-key
# For Claude agents
ANTHROPIC_API_KEY=your-anthropic-api-key或者将它们设置为环境变量：
export OPENAI_API_KEY=your-openai-api-key
export ANTHROPIC_API_KEY=your-anthropic-api-key您还可以在YAML配置中使用秘密引用进行指定：
agents:
my_openai_agent:
provider: openai
api_key: ${{ secrets.OPENAI_API_KEY }}
my_claude_agent:
provider: claude
api_key: ${{ secrets.ANTHROPIC_API_KEY }}项目结构
light-agent/
├── main.py # Main entry point
├── pyproject.toml # Project configuration and dependencies
├── .env # Environment variables (not in git)
├── configs/
│ ├── prompts/ # Reusable prompt files
│ │ ├── base_assistant.txt
│ │ └── kubernetes_expert.txt
│ ├── sample/
│ │ ├── agent.yaml # Basic example
│ │ ├── agent_with_files.yaml # File-based prompts example
│ │ └── agent_full_options.yaml # Comprehensive options
│ └── test/ # Test configurations
├── src/
│ └── ai_agent/
│ ├── __init__.py # Package initialization
│ ├── config_loader.py # Configuration parsing
│ ├── tools_pool.py # Tools management
│ ├── agent_factory.py # Agent creation
│ ├── workflow_executor.py # Workflow orchestration
│ └── providers/ # AI provider implementations
│ ├── __init__.py
│ ├── base_provider.py # Provider interface
│ ├── openai/ # OpenAI provider
│ │ └── openai_provider.py
│ └── claude/ # Claude provider
│ └── claude_provider.py
├── tests/ # Unit and integration tests
├── outputs/ # Workflow outputs directory
└── docs/
└── AGENT_CONFIG_GUIDE.md # Detailed configuration guide关键组件
配置加载器
解析YAML配置并验证结构。支持：
- 元数据和注释
- MCP服务器配置的工具定义
- 多个AI提供商（OpenAI、Claude）
- 基于文件的系统提示与内容合并
- 特定于提供商的选项（切换、权限等）
- 带有模型参数的代理配置
- 带有输出的工作流步骤定义
工具库
管理共享工具池：
- 启动并连接到MCP服务器（本地或远程）
- 按名称向代理提供工具
- 处理MCP连接的清理
提供商系统
抽象不同的AI提供商：
- 所有提供者的通用接口
- 使用OpenAI代理SDK的OpenAI提供商
- Claude提供者使用Claude代理sdk
- 易于与新提供商扩展
代理工厂
创建代理实例：
- 根据YAML规范配置代理
- 处理API密钥管理（环境变量和机密）
- 从共享池中分配工具
- 应用特定于提供商的配置
工作流执行器
执行工作流：
- 按顺序运行代理步骤
- 在步骤之间传递上下文
- 收集和汇总结果
- 处理输出保存到文件
- 支持并行执行（未来增强）
MCP服务器支持
系统支持两种类型的MCP服务器：
本地MCP服务器
Tools:
- name: my_tool
description: My local MCP tool
mcp_server:
type: local
command: /path/to/mcp-server
args: ["--option1", "value1"]远程MCP服务器
Tools:
- name: my_tool
description: My remote MCP tool
mcp_server:
type: remote
url: http://localhost:8080/mcpMCP服务器类型
系统支持多种类型的MCP服务器：
本地/STDIO MCP服务器：
Tools:
- name: shell_mcp
description: shell access for LLM
mcp_server:
type: local # or 'stdio' - both are supported
command: npx
args:
- "mcp-remote"
- "http://localhost:8080/mcp"
- "--allow-http"
env:
DEBUG: "true"
# For mcp-remote proxies, timeout defaults to 60s (auto-detected)
# Override if needed:
timeout: 120.0SSE MCP服务器：
Tools:
- name: sse_tool
description: SSE-based MCP tool
mcp_server:
type: sse
url: https://api.example.com/mcp/sse
timeout: 60.0
sse_read_timeout: 300.0流式HTTP MCP服务器：
Tools:
- name: remote_api
description: Remote API access via streamable HTTP
mcp_server:
type: streamable_http
url: https://api.example.com/mcp
timeout: 60.0
sse_read_timeout: 300.0自动重试SSE断开连接：
系统自动处理SSE流断开（常见于 mcp-remote 以及远程MCP服务器），具有：
- 最多3次重试尝试，具有指数回退
- 自动超时增加到60秒
mcp-remote代理 - 重试尝试的详细日志记录
工具名称前缀
为了避免在使用多个MCP服务器时发生命名冲突，系统会自动在所有工具名称前加上MCP服务器名称。格式为： _.
例如，如果您定义了一个名为的MCP服务器 shell_mcp_http 提供如下工具 execute_command 和 list_files，它们将作为：
shell_mcp_http_execute_commandshell_mcp_http_list_files
这确保了来自不同MCP服务器的工具永远不会冲突，即使它们具有相同的原始名称。
高级功能
基于文件的系统提示
从外部文件加载提示以更好地组织：
agents:
my_agent:
provider: openai
model: gpt-4
prompts:
system:
files:
- prompts/base_assistant.txt
- prompts/domain_expertise.txt或者将内联内容与文件结合：
agents:
my_agent:
provider: openai
model: gpt-4
prompts:
system:
content: |
You are a specialized assistant.
files:
- prompts/base_assistant.txt看 configs/sample/agent_with_files.yaml 查看完整示例。
提供商特定选项
配置特定于提供程序的行为：
OpenAI选项：
agents:
my_agent:
provider: openai
model: gpt-4
options:
openai:
handoff_description: "Use this agent for database tasks"克劳德选项：
agents:
my_agent:
provider: claude
model: claude-3-opus-20240229
options:
claude:
allowed_tools: [tool1, tool2]
max_turns: 100
permission_mode: auto
cwd: /workspace
env:
CUSTOM_VAR: value看 docs/AGENT_CONFIG_GUIDE.md 获取完整的选项文档。
工作流输出
将代理响应保存到文件：
workflows:
steps:
- id: analysis
agent: analyst_agent
prompt: "Analyze the system"
outputs:
- type: text
destination: reports/analysis.txt
- type: text
destination: outputs/latest.txt目录是自动创建的。
发展
编码结构
- 所有代码都包含全面的注释
- 遵循Python最佳实践和PEP 8
- 使用类型提示以获得更好的IDE支持
- 包括用于调试和监控的日志记录
- 用Ruff格式化
运行测试
# Run tests with uv
uv run pytest
# Run specific test
uv run pytest tests/test_unit.py代码格式化
# Format code with Ruff
uv run ruff format .
# Check linting
uv run ruff check .扩展系统
要添加新功能，请执行以下操作：
- 新的人工智能提供商：在中创建新的提供程序类
src/ai_agent/providers/ - 新工具类型：扩展
ToolsPool类 - 自定义代理行为：修改
AgentFactory - 工作流模式：增强
WorkflowExecutor - 配置选项：更新
ConfigLoader数据类
示例工作流程
简单的单代理任务
workflows:
steps:
- id: analyze
agent: analyst_agent
prompt: "Analyze the current system status"
outputs:
- type: text
destination: outputs/analysis.txt多供应商协调
workflows:
steps:
- id: gather_data
agent: openai_agent
prompt: "Collect and analyze system metrics"
outputs:
- type: text
destination: reports/openai_analysis.txt
- id: review
agent: claude_agent
prompt: "Review the previous analysis and provide insights"
outputs:
- type: text
destination: reports/claude_review.txt
- id: recommend
agent: advisor_agent
prompt: "Synthesize findings and provide recommendations"
outputs:
- type: text
destination: reports/final_recommendations.txt跨平台比较
workflows:
steps:
- id: openai_approach
agent: openai_specialist
prompt: "Solve this problem using your approach"
outputs:
- type: text
destination: outputs/openai_solution.txt
- id: claude_approach
agent: claude_specialist
prompt: "Solve the same problem using your approach"
outputs:
- type: text
destination: outputs/claude_solution.txt故障排除
常见问题
- 导入错误：确保安装了所有依赖项(
uv pip install -e .) - API密钥错误：设置
OPENAI_API_KEY和ANTHROPIC_API_KEY环境变量或创建.env文件 - MCP连接错误：验证MCP服务器是否正在运行且可访问
- 未找到提示文件：确保提示文件路径正确（相对于配置文件或绝对路径）
- 未找到提供商：检查提供程序名称是否为
openai或claude - 配置拼写错误：使用
--validate检查拼写错误并获得更正建议
配置验证功能
验证器提供智能错误消息：
- 缺少必填字段：明确指出缺失的内容和预期的内容
- 伤寒检测：模糊匹配，建议更正拼写错误的字段名
- 类型验证：确保字段具有正确的数据类型
- 未知字段警告：提醒您不要使用的字段
带有拼写错误的验证输出示例：
uv run python src/main.py -c config.yaml --validate
⚠️ Agent 'my_agent': Unknown field 'temperatur' found. Did you mean: 'temperature'?
⚠️ Workflow step #1: Unknown field 'max_turn' found. Did you mean: 'max_turns'?
ERROR: Workflow step #1: Missing required field(s): 'prompt'
Hint: Found similar field 'promt' - did you mean 'prompt'?调试模式
默认情况下，应用程序会记录详细信息。检查控制台输出：
- 配置加载状态
- 代理创建进度
- 工作流执行步骤
- 工具调用
- 带有堆栈跟踪的错误消息
测试您的配置
在运行完整工作流之前，请验证您的配置：
# Test with a simple workflow
uv run python src/main.py
# Check logs for configuration errors
# The system will report detailed validation errors获取帮助
- 看
docs/AGENT_CONFIG_GUIDE.md获取全面的配置文档 - 检查中的示例配置
configs/sample/ - 查看中的测试文件
tests/关于使用模式
许可证
本项目按原样提供，用于教育和发展目的。
示例配置
该项目包括几个示例配置：
configs/sample/agent.yaml：显示OpenAI和Claude代理的基本配置configs/sample/agent_with_files.yaml：演示基于文件的提示加载configs/sample/agent_full_options.yaml：包含所有可用选项的综合示例
贡献
欢迎投稿！请确保：
- 代码遵循PEP 8风格指南（由Ruff执行）
- 所有函数均包含文档字符串
- 类型提示贯穿始终
- 变化经过了很好的测试
- 跑
uv run ruff format .在承诺之前 - 提交消息清楚地描述了更改
开发工作流程
- 克隆存储库
- 创建虚拟环境：
uv venv - 安装依赖项：
uv pip install -e ".[dev]" - 进行更改
- 运行测试：
uv run pytest - 格式代码：
uv run ruff format . - 检查绒毛：
uv run ruff check . - 提交拉取请求