使用说明

技术研究代理

一个由Strands Agents和Firecrawl MCP服务器构建的会话研究代理，通过基于终端的REPL接口提供智能网络抓取和技术文档分析。

特性

🔍 智能网络研究

使用Firecrawl MCP服务器进行高级网络抓取
智能内容提取和分析
代码示例标识和格式
技术文档解析

🤖 对话式AI

使用Strands代理进行上下文感知对话
后续问题建议
会话持久性和历史
多回合对话支持

💻 终端REPL接口

具有语法突出显示的丰富终端格式
交互式指挥系统
会话管理
实时研究成果

📚 技术重点

专门用于代码示例和文档
编程语言检测
API端点提取
最佳实践识别

快速开始

先决条件

Python 3.8或更高版本
Node.js（用于Firecrawl MCP服务器）
Firecrawl API密钥

快速演示（无需依赖关系）

在不安装任何依赖项的情况下尝试research agent演示：

# See what the agent can do
python run.py demo

# View project information
python run.py info

# Check dependency status
python run.py check

完整安装

克隆并设置项目：

git clone <repository-url>
cd research-agent

运行自动安装程序：

./install.sh

或手动安装：

pip install -r requirements.txt
npm install -g firecrawl-mcp
export FIRECRAWL_API_KEY=your_api_key_here

运行研究代理：

python main.py

配置

模型提供程序配置

研究代理支持多个AI模型提供商：

OpenAI模型

要使用OpenAI模型，您需要：

安装 OpenAI 依赖项：
```
pip install 'strands-agents[openai]'
```

设置您的OpenAI API密钥：

export OPENAI_API_KEY="your-api-key-here"

可选：为OpenAI兼容端点设置自定义基URL：

export OPENAI_BASE_URL="https://your-custom-endpoint.com/v1"

在中配置您的模型 config/agent_config.yaml:

agent:
  name: "Technical Research Assistant"
  provider: "openai"
  model_id: "gpt-4o"
  model_params:
    temperature: 0.7
    max_tokens: 1000

LiteLLM与Gemini模型

通过LiteLLM使用谷歌的Gemini模型：

安装 LiteLLM 依赖项：
```
pip install 'strands-agents[litellm]'
```

设置您的Google AI Studio API密钥：

export GEMINI_API_KEY="your-gemini-api-key-here"

在中配置您的模型 config/agent_config.yaml:

agent:
  name: "Technical Research Assistant"
  provider: "litellm"
  model_id: "gemini/gemini-2.0-flash"
  model_params:
    temperature: 0.7
    max_tokens: 1000
    safety_settings:
      - category: "HARM_CATEGORY_HARASSMENT"
        threshold: "BLOCK_MEDIUM_AND_ABOVE"

或使用自动检测：

agent:
  model: "gemini/gemini-2.0-flash"  # Auto-detected as litellm provider

人/基岩模型（默认）

agent:
  name: "Technical Research Assistant"
  provider: "anthropic"
  model_id: "claude-3-sonnet"

向后兼容

现有配置继续工作：

agent:
  name: "Technical Research Assistant"
  model: "us.anthropic.claude-sonnet-4-20250514-v1:0"  # Auto-detected

支持的型号

OpenAI：OpenAI API支持的任何型号ID（gpt-4o、gpt-4o-mini、gpt-4-turbo、gpt-3.5-turbo等）
文学硕士/双子座：所有双子座型号（双子座/双子座-2.0-flash、双子座/双子座-1.5-pro、双子座/双子pro等）
Anthropic：通过Bedrock或直接API的Claude模型
自定义：任何与OpenAI兼容的端点

完整配置示例

agent:
  name: "Technical Research Assistant"
  provider: "openai"
  model_id: "gpt-4o"
  model_params:
    temperature: 0.7
    max_tokens: 1000
  max_context_length: 8000

research:
  max_sources_per_query: 5
  content_extraction_timeout: 30
  enable_code_analysis: true
  enable_documentation_parsing: true

conversation:
  enable_follow_ups: true
  context_window_size: 10
  auto_suggest_refinements: true

mcp:
  firecrawl_server_timeout: 60
  retry_attempts: 3
  batch_size: 3

看 examples/openai_config.yaml 更多配置示例。

使用示例

基础研究查询

Research> How do I implement JWT authentication in FastAPI?

🔍 Searching for FastAPI JWT authentication information...
📄 Found 3 relevant sources:
   • FastAPI Security Documentation
   • JWT Authentication Tutorial
   • OAuth2 Implementation Guide

📋 FastAPI JWT Authentication Overview:
FastAPI provides built-in security utilities for implementing JWT authentication...

💡 Code Example:
```python
from fastapi import FastAPI, Depends, HTTPException
from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
import jwt

app = FastAPI()
security = HTTPBearer()

def verify_token(credentials: HTTPAuthorizationCredentials = Depends(security)):
    token = credentials.credentials
    try:
        payload = jwt.decode(token, SECRET_KEY, algorithms=["HS256"])
        return payload
    except jwt.PyJWTError:
        raise HTTPException(status_code=401, detail="Invalid token")

🤔 后续建议：

如何在FastAPI中处理令牌刷新？
JWT的安全最佳实践是什么？
如何实现基于角色的访问控制？


### Interactive Follow-up

研究>2

🔍 分析JWT安全最佳实践。..

📋 JWT安全最佳实践：以下是JWT实现的基本安全考虑因素。..

💡 关键安全措施：

使用强密钥（最小256位）
实现令牌过期
仅使用HTTPS
验证所有索赔
实施适当的错误处理

🤔 下一步： •您想看到令牌刷新实现吗？ •您对JWT有效载荷结构感兴趣吗？


## REPL Commands

| Command | Description |
|---------|-------------|
| `/help` | Show available commands |
| `/sessions` | List recent research sessions |
| `/load <id>` | Load a previous session |
| `/new [title]` | Start a new research session |
| `/history` | Show current session history |
| `/clear` | Clear the screen |
| `/quit`, `/exit` | Exit the research agent |

## Architecture

The research agent consists of several key components:

### Core Components

- **Research Agent** (`research_agent.py`): Main orchestrator using Strands Agents
- **MCP Integration** (`mcp_integration.py`): Firecrawl MCP server client
- **Content Processor** (`content_processor.py`): Web content analysis and extraction
- **Session Manager** (`session_manager.py`): Conversation history and persistence
- **REPL Interface** (`research_repl.py`): Terminal-based user interface

### Utility Modules

- **Formatters** (`utils/formatters.py`): Output formatting and display
- **Extractors** (`utils/extractors.py`): Content extraction utilities
- **Validators** (`utils/validators.py`): Input validation and sanitization

## API Integration

### Firecrawl MCP Server

The agent integrates with Firecrawl through the MCP (Model Context Protocol):

```python
# Connect to Firecrawl MCP server
async with FirecrawlMCPClient() as client:
    # Search the web
    results = await client.search_web("FastAPI authentication", num_results=5)
    
    # Crawl specific URLs
    content = await client.crawl_url("https://fastapi.tiangolo.com/tutorial/security/")
    
    # Batch processing
    batch_results = await client.batch_crawl(urls)

Strands代理集成

from strands import Agent

# Create agent with MCP tools
agent = Agent(
    name="Technical Research Assistant",
    model="claude-3-sonnet",
    tools=mcp_tools,
    system_prompt=research_prompt
)

# Process research query
response = await agent.arun(query_with_context)

发展

项目结构

research-agent/
├── src/
│   ├── research_agent.py          # Main agent implementation
│   ├── research_repl.py           # REPL interface
│   ├── mcp_integration.py         # MCP client
│   ├── content_processor.py       # Content analysis
│   ├── session_manager.py         # Session handling
│   └── utils/
│       ├── formatters.py          # Output formatting
│       ├── extractors.py          # Content extraction
│       └── validators.py          # Input validation
├── config/
│   └── agent_config.yaml          # Configuration
├── data/
│   └── sessions/                  # Session storage
├── requirements.txt               # Dependencies
├── setup.py                       # Package setup
└── README.md                      # Documentation

运行测试

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/

# Run with coverage
pytest --cov=src tests/

代码质量

# Format code
black src/

# Lint code
flake8 src/

# Type checking
mypy src/

环境变量

变量	描述	必填
`FIRECRAWL_API_KEY`	您的Firecrawl API密钥	是
`OPENAI_API_KEY`	您的OpenAI API密钥（用于OpenAI模型）	是（用于Open人工智能）
`OPENAI_BASE_URL`	自定义OpenAI兼容端点URL	否
`RESEARCH_AGENT_CONFIG_PATH`	配置文件路径	否
`RESEARCH_AGENT_DATA_PATH`	数据目录路径	否

故障排除

常见问题

1.MCP服务器连接失败

❌ Failed to connect to Firecrawl MCP server

确保安装了Firecrawl MCP服务器： npm install -g firecrawl-mcp
检查您的API密钥是否已设置： echo $FIRECRAWL_API_KEY
验证网络连接

2.找不到配置文件

❌ Configuration file not found: config/agent_config.yaml

确保从项目根目录运行
检查配置文件是否存在并且可读

3.导入错误

ImportError: No module named 'strands'

安装依赖项： pip install -r requirements.txt
考虑使用虚拟环境

调试模式

通过在配置中设置日志级别来启用调试日志记录：

logging:
  level: DEBUG
  file: research_agent.log

贡献

分叉存储库
创建要素分支： git checkout -b feature-name
进行更改并添加测试
运行测试套件： pytest
提交拉取请求

许可证

此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。

致谢

Strands代理商 -AI代理框架
萤火虫 -Web抓取服务
富有的 -终端格式化库

支持

有关支持和问题：

在GitHub上创建问题
查看[project-docs url]上的文档
加入我们的社区讨论

快乐的研究！ 🔬🤖