# agent

**Repository Path**: qchen007/agent

## Basic Information

- **Project Name**: agent
- **Description**: agent
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-13
- **Last Updated**: 2026-06-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Agent Service

An intelligent Agent service built on Python 3.14+, providing HTTP API via FastAPI with LangGraph/LangChain for Agent workflows.

## Features

- **Multi-mode Agent**: Supports three modes: single Agent with tools, skill-driven Agent, and multi-Agent collaboration
- **Skill System**: Dynamically loads Markdown skill files from `skills/` directory, auto-matches user intent
- **Multi-Agent Collaboration**: Supports SubAgent auto-dispatch and Supervisor state machine routing
- **Dual Response Modes**: Direct response and streaming output (SSE)
- **Session Management**: Agent supports concurrent multi-session via session_id isolation
- **Shared Tool Library**: `src/tools/` provides search, calculator, datetime, file, URL and other common tools

## Quick Start

```bash
# Install dependencies
uv sync

# Start dev server (auto-reload)
uv run uvicorn main:app --reload --port 8000
```

## Environment Configuration

Copy `.env.example` to `.env` and configure:

```env
OPENAI_API_KEY=sk-xxx
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-4o-mini
TAVILY_API_KEY=tvly-xxx  # Optional, required for search
```

## Agent Modes

### 1. Single Agent (Tool Calling)

Uses LangGraph + built-in tools, suitable for general conversation tasks.

```bash
curl -X POST http://localhost:8000/api/agent/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello", "session_id": "user123"}'
```

### 2. Skill-driven Agent

Based on `deepagents`, loads Markdown skill files from `skills/` directory, Agent automatically matches appropriate skills.

```bash
curl -X POST http://localhost:8000/api/skillagent/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Help me write some Python code"}'
```

### 3. Multi-Agent Collaboration

**SubAgent Mode**: Auto-dispatches predefined sub-agents (researcher/coder/writer).

```bash
curl -X POST http://localhost:8000/api/multiagent/subagent/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Calculate 2+2"}'
```

**Supervisor Mode**: LLM-driven state machine, routes to different expert Agents based on conversation content.

```bash
curl -X POST http://localhost:8000/api/multiagent/supervisor/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Search and summarize Python async programming"}'
```

## Built-in Tools

| Tool | Description |
|------|-------------|
| `search_web` | Web search (requires TAVILY_API_KEY) |
| `calculator` | Math operations (+, -, *, /, //, %, **, abs, max, min, round, sum, pow) |
| `get_current_time` | Get current time |
| `fetch_url` | Fetch web page content |
| `read_file` / `write_file` | File read/write |
| `count_words` | Count words |
| `random_number` | Generate random number |

## Streaming Output

All `/chat` endpoints support `/chat/stream` streaming output via SSE protocol.

```bash
curl -X POST http://localhost:8000/api/agent/chat/stream \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello"}'
```

SSE event types: `start` / `chunk` / `tool_call` / `tool_result` / `done`

## Direct LLM Call

No Agent, no tools, suitable for simple requests.

```bash
curl -X POST http://localhost:8000/api/llm/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello"}'
```

## User Management

```bash
# Create user
curl -X POST http://localhost:8000/api/users/ \
  -H "Content-Type: application/json" \
  -d '{"name": "John", "email": "john@example.com"}'

# List users
curl http://localhost:8000/api/users/list
```

## Health Check

```bash
curl http://localhost:8000/liveness
curl http://localhost:8000/readiness
```

## Project Structure

```
src/
├── routes.py              # Aggregate all routes
├── config/                # pydantic-settings configuration
├── common/                # Shared utilities
│   ├── agent_utils.py     # Agent common logic (create_chat_model, etc.)
│   └── middleware.py      # Middleware
├── tools/                 # Tool definitions
│   ├── calculator.py      # Math calculator
│   ├── datetime_tools.py  # Date/time tools
│   ├── file_tools.py      # File read/write
│   ├── random_tools.py    # Random number generation
│   ├── search.py          # Web search
│   ├── text_tools.py      # Text processing
│   └── url_tools.py       # URL processing
├── agent/                 # Single Agent + tool calling
│   ├── api.py
│   ├── service.py
│   └── models.py
├── skillagent/            # Skill-driven Agent
│   ├── api.py
│   ├── service.py
│   └── models.py
├── multiagent/            # Multi-Agent collaboration
│   ├── subagent/          # SubAgent auto-dispatch
│   └── supervisor/       # Supervisor state machine
└── llm/                   # Direct LLM call
    ├── api.py
    ├── service.py
    └── models.py

skills/                    # Skill definitions (Markdown files)
├── coding/SKILL.md
├── web-research/SKILL.md
└── writing/SKILL.md
```

## Code Standards

- Python 3.14+, all functions must have type annotations
- Use ruff for linting: `uv run ruff check .`
- Formatting: double quotes, 100 character line length

## Testing

```bash
# Run all tests
uv run pytest tests/

# Run single test file
uv run pytest tests/test_agent.py

# Run single test
uv run pytest tests/test_agent.py::test_agent_chat -v
```