claude-multi-agent-api-server

KO | EN

gitlite — search

#python #ai #llm #go #deep-learning #linux #macos #awesome #vue #security #mcp #ios #openai #open-source

claude-multi-agent-api-server

(★ 13)

Production-ready FastAPI service for concurrent Claude Agent session management with real-time monitoring, cost tracking, and session resumption via HTTP API.

claude-multi-agent-api-server 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

> [!WARNING]
> Development of this repository has ceased.  
> It is currently being redeveloped as a resident AI agent; [OpenClaude](https://github.com/is0383kk/openclaude).

# Claude Multi-Agent API Server

A production-ready FastAPI web service that enables concurrent execution and management of multiple Claude Agent sessions via HTTP API.  
Features advanced multi-agent session management with independent lifecycle control, real-time monitoring of each agent's progress, cost tracking per session, session resumption capabilities, and comprehensive background task orchestration for scalable AI agent deployment.

## ■ Available API Endpoints

| Endpoint                  | Method | Description                                        |
| ------------------------- | ------ | -------------------------------------------------- |
| `/`                       | GET    | Basic API information and available endpoints list |
| `/execute/`               | POST   | Start a new Claude agent session                   |
| `/status/{session_id}`    | GET    | Get session status, message history, and results   |
| `/cancel/{session_id}`    | POST   | Cancel a running session                           |
| `/sessions/`              | GET    | Get detailed information of all active sessions    |
| `/sessions/{session_id}`  | DELETE | Delete a specific session by ID                    |
| `/sessions/cleanup`       | DELETE | Clean up old sessions                              |

## ■ File Structure

```
Claude-Multi-Agent-API-Server/
├── main.py                 # Main FastAPI application file
├── models.py               # Pydantic model definitions and validation
├── session_manager.py      # Session lifecycle management
├── examples/                # Usage examples and test files
│   ├── client_example.py   # Production-ready Python client implementation example
│   └── index.html          # Interactive web test interface
└── requirements.txt        # Python dependency definitions
```

# 1. API Endpoints

## ■ Agent Execution (`POST /execute/`)

Execute agents using Claude Agent SDK.

**Request Body Example:**

```json
{
  "prompt": "Please explain Claude Agent SDK in detail",
  "system_prompt": "You are an excellent system engineer",
  "permission_mode": "acceptEdits",
  "model": "sonnet",
  "cwd": "/path/to/working/directory",
  "allowed_tools": ["Read", "Write", "Bash"]
}
```

**Response Example:**

```json
{
  "session_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "pending",
  "message": "Session 123e4567-e89b-12d3-a456-426614174000 started successfully"
}
```

## ■ Status Check (`GET /status/{session_id}`)

Get the status of a running agent.

**Response Example:**

```json
{
  "session_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "running",
  "messages": [
    {
      "type": "UserMessage",
      "content": "...",
      "timestamp": "2024-01-01T12:00:00.000Z"
    },
    {
      "type": "AssistantMessage",
      "content": "...",
      "timestamp": "2024-01-01T12:00:01.000Z"
    }
  ],
  "result": null,
  "error": null,
  "duration_ms": 1000,
  "total_cost_usd": 0.01
}
```

**Status Values:**

- `pending`: Just after session creation
- `running`: Agent is executing
- `completed`: Successfully completed
- `error`: An error occurred
- `cancelled`: Cancelled

## ■ Agent Execution Cancellation (`POST /cancel/{session_id}`)

Cancel a running agent.

**Response Example:**

```json
{
  "session_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "cancelled",
  "message": "Session 123e4567-e89b-12d3-a456-426614174000 cancelled successfully"
}
```

## ■ Session List Retrieval (`GET /sessions/`)

Get detailed information of all active sessions.

**Response Example:**

```json
[
  {
    "session_id": "123e4567-e89b-12d3-a456-426614174000",
    "status": "running",
    "prompt": "Create a Hello World program in Python",
    "created_at": "2024-01-01T12:00:00.000Z",
    "start_time": "2024-01-01T12:00:01.000Z",
    "end_time": null,
    "error": null,
    "result": null,
    "message_count": 5
  }
]
```

## ■ Individual Session Deletion (`DELETE /sessions/{session_id}`)

Delete a specific session by session ID.

**Path Parameters:**

- `session_id`: Session ID to delete

**Response Example:**

```json
{
  "session_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "completed",
  "message": "Session 123e4567-e89b-12d3-a456-426614174000 deleted successfully"
}
```

**Error Responses:**

- `404 Not Found`: Session does not exist
- `400 Bad Request`: Cannot delete running sessions (must be cancelled first)

**Notes:**

- Only sessions with status `completed`, `cancelled`, `error`, or `pending` can be deleted
- Running sessions must be cancelled first using `/cancel/{session_id}`
- Deleted sessions cannot be resumed

## ■ Old Session Cleanup (`DELETE /sessions/cleanup`)

Delete sessions older than the specified time.

**Query Parameters:**

- `max_age_hours`: Maximum retention time (default: 24 hours)

**Response Example:**

```json
{
  "removed": 5,
  "message": "Cleaned up 5 old sessions"
}
```

# 2. Setup and Execution

## ■ Prerequisites

- Python 3.8 or higher
- Claude Code CLI (`npm install -g @anthropic-ai/claude-code`)

## ■ Library Installation

```bash
pip install -r requirements.txt
```

## ■ Server Startup

```bash
python main.py
```

or

```bash
uvicorn main:app --reload --host 0.0.0.0 --port 8000
```

# 3. Quick Start

## ■ Pattern 1: Test with Web Interface

After starting the server, open `examples/index.html` in a browser for GUI operation.

![Web Interface Screenshot](https://raw.githubusercontent.com/is0383kk/claude-multi-agent-api-server/main/img/001.png)

The web interface provides:

- **Agent Execution**: Execute agents with configurable options (prompt, model, permission mode, etc.)
- **Session Status Check**: Monitor session status and view message history
- **Active Sessions List**: View all active sessions with resume and cancel capabilities

## ■ Pattern 2: Test with Python Client

Running `examples/client_example.py` executes batch processing for all API endpoints.

```python
python examples/client_example.py
```

# 4. Important Notes and Best Practices

## ■ Memory Management

- Sessions are stored in memory and are not automatically deleted
- Regularly clean up with `/sessions/cleanup` or restart the server

## ■ Performance

- Long-running agents continue to consume server resources
- Be mindful of the number of concurrent sessions
- Actively cancel unnecessary sessions

## ■ Security

- Configure CORS settings appropriately for production environments

## ■ License

MIT License

---

# Claude Multi-Agent API Server

複数の Claude Agent セッションの同時実行と管理を可能にした FastAPI Web サービスです。  
高度なマルチエージェントセッション管理機能により、各エージェントの独立したライフサイクル制御、セッション毎のリアルタイム進捗監視、コスト追跡、セッション再開機能、およびスケーラブルな AI エージェント展開のための包括的なバックグラウンドタスク オーケストレーションを提供します。

## ■ 提供している API エンドポイント一覧

| エンドポイント            | メソッド | 説明                                         |
| ------------------------- | -------- | -------------------------------------------- |
| `/`                       | GET      | API の基本情報と利用可能エンドポイント一覧   |
| `/execute/`               | POST     | 新しい Claude エージェントセッションを開始   |
| `/status/{session_id}`    | GET      | セッションの状態、メッセージ履歴、結果を取得 |
| `/cancel/{session_id}`    | POST     | 実行中のセッションをキャンセル               |
| `/sessions/`              | GET      | すべてのアクティブセッションの詳細情報を取得 |
| `/sessions/{session_id}`  | DELETE   | 指定したセッションIDで個別にセッションを削除 |
| `/sessions/cleanup`       | DELETE   | 古いセッションをクリーンアップ               |

## ■ ファイル構成

```
Claude-Multi-Agent-API-Server/
├── main.py                 # FastAPIアプリケーションのメインファイル
├── models.py               # Pydanticモデル定義とバリデーション
├── session_manager.py      # セッションライフサイクル管理
├── examples/                # 使用例とテスト用ファイル
│   ├── client_example.py   # 本格的なPythonクライアント実装例
│   └── index.html          # インタラクティブWebテストインターフェース
└── requirements.txt        # Python依存パッケージ定義
```

# 1. API エンドポイントについて

## ■ エージェント実行 (`POST /execute/`)

Claude Agent SDK によるエージェントを実行します。

**リクエストボディ例:**

```json
{
  "prompt": "Claude Agent SDKについて詳しく解説してください",
  "system_prompt": "あなたは優秀なシステムエンジニアです",
  "permission_mode": "acceptEdits",
  "model": "sonnet",
  "cwd": "/path/to/working/directory",
  "allowed_tools": ["Read", "Write", "Bash"]
}
```

**レスポンス例:**

```json
{
  "session_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "pending",
  "message": "Session 123e4567-e89b-12d3-a456-426614174000 started successfully"
}
```

## ■ ステータス確認 (`GET /status/{session_id}`)

実行中のエージェントのステータスを取得します。

**レスポンス例:**

```json
{
  "session_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "running",
  "messages": [
    {
      "type": "UserMessage",
      "content": "...",
      "timestamp": "2024-01-01T12:00:00.000Z"
    },
    {
      "type": "AssistantMessage",
      "content": "...",
      "timestamp": "2024-01-01T12:00:01.000Z"
    }
  ],
  "result": null,
  "error": null,
  "duration_ms": 1000,
  "total_cost_usd": 0.01
}
```

**ステータス値:**

- `pending`: セッション作成直後
- `running`: エージェント実行中
- `completed`: 正常に完了
- `error`: エラーが発生
- `cancelled`: キャンセルされた

## ■ エージェント実行中断 (`POST /cancel/{session_id}`)

実行中のエージェントを中断します。

**レスポンス例:**

```json
{
  "session_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "cancelled",
  "message": "Session 123e4567-e89b-12d3-a456-426614174000 cancelled successfully"
}
```

## ■ セッション一覧取得 (`GET /sessions/`)

すべてのアクティブセッションの詳細情報を取得します。

**レスポンス例:**

```json
[
  {
    "session_id": "123e4567-e89b-12d3-a456-426614174000",
    "status": "running",
    "prompt": "PythonでHello Worldプログラムを作成してください",
    "created_at": "2024-01-01T12:00:00.000Z",
    "start_time": "2024-01-01T12:00:01.000Z",
    "end_time": null,
    "error": null,
    "result": null,
    "message_count": 5
  }
]
```

## ■ 個別セッションの削除 (`DELETE /sessions/{session_id}`)

セッションIDを指定して個別にセッションを削除します。

**パスパラメータ:**

- `session_id`: 削除するセッション ID

**レスポンス例:**

```json
{
  "session_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "completed",
  "message": "Session 123e4567-e89b-12d3-a456-426614174000 deleted successfully"
}
```

**エラーレスポンス:**

- `404 Not Found`: セッションが存在しない
- `400 Bad Request`: 実行中のセッションは削除できません（先にキャンセルが必要）

**注意事項:**

- `completed`、`cancelled`、`error`、`pending` 状態のセッションのみ削除可能
- 実行中のセッションは先に `/cancel/{session_id}` でキャンセルする必要があります
- 削除されたセッションは再開できません

## ■ 古いセッションのクリーンアップ (`DELETE /sessions/cleanup`)

指定した時間より古いセッションを削除します。

**クエリパラメータ:**

- `max_age_hours`: 保持する最大時間（デフォルト: 24 時間）

**レスポンス例:**

```json
{
  "removed": 5,
  "message": "Cleaned up 5 old sessions"
}
```

# 2. 実行方法

## ■ 前提条件

- Python 3.8 以上
- Claude Code CLI (`npm install -g @anthropic-ai/claude-code`)

## ■ ライブラリのインストール

```bash
pip install -r requirements.txt
```

## ■ サーバーの起動

```bash
python main.py
```

または

```bash
uvicorn main:app --reload --host 0.0.0.0 --port 8000
```

# 3. クイックスタート

## ■ パターン１：Web インターフェースでテスト

サーバーを起動した後、`examples/index.html`をブラウザで開いて GUI で操作できます。

![Web インターフェーススクリーンショット](https://raw.githubusercontent.com/is0383kk/claude-multi-agent-api-server/main/img/001.png)

Web インターフェースでは以下の機能が利用できます：

- **エージェント実行**: プロンプト、モデル、許可モードなどを設定してエージェントを実行
- **セッション状態確認**: セッションのステータス監視とメッセージ履歴の表示
- **アクティブセッション一覧**: すべてのアクティブセッションの表示、再開、キャンセル機能

## ■ パターン２：Python クライアントでテスト

`examples/client_example.py`を実行すると、API エンドポイントで定義されている処理を一括実行できます。

```python
python examples/client_example.py
```

# 4. 注意事項とベストプラクティス

## ■ メモリ管理

- セッションはメモリ内に保存され、自動削除されません
- 定期的に `/sessions/cleanup` でクリーンアップかサーバの再起動をしてください

## ■ パフォーマンス

- 長時間実行エージェントはサーバーリソースを消費し続けます
- 同時実行セッション数に注意してください
- 不要なセッションは積極的にキャンセルしてください

## ■ セキュリティ

- 本番環境では CORS 設定を適切に配置してください

## ■ ライセンス

MIT License

claude-multi-agent-api-server

claude-multi-agent-api-server 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

claude-multi-agent-api-server

claude-multi-agent-api-server 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README