https://github.com/is0383kk/claude-multi-agent-api-server

Production-ready FastAPI service for concurrent Claude Agent session management with real-time monitoring, cost tracking, and session resumption via HTTP API.
https://github.com/is0383kk/claude-multi-agent-api-server

agentic-ai agents ai-agents anthropic api api-client api-server claude claude-agent-sdk claude-agents claude-code claude-code-sdk fastapi multi-agent multi-agent-systems multiagent multiagent-systems rest-api session-management

Last synced: 8 days ago
JSON representation

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

• Host: GitHub
• URL: https://github.com/is0383kk/claude-multi-agent-api-server
• Owner: is0383kk
• License: mit
• Created: 2025-11-02T13:29:00.000Z (7 months ago)
• Default Branch: main
• Last Pushed: 2026-05-09T18:49:24.000Z (15 days ago)
• Last Synced: 2026-05-09T20:38:48.271Z (14 days ago)
• Topics: agentic-ai, agents, ai-agents, anthropic, api, api-client, api-server, claude, claude-agent-sdk, claude-agents, claude-code, claude-code-sdk, fastapi, multi-agent, multi-agent-systems, multiagent, multiagent-systems, rest-api, session-management
• Language: Python
• Homepage:
• Size: 2.22 MB
• Stars: 13
• Watchers: 0
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

          
> [!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](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 インターフェーススクリーンショット](img/001.png)

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

- **エージェント実行**: プロンプト、モデル、許可モードなどを設定してエージェントを実行

- **セッション状態確認**: セッションのステータス監視とメッセージ履歴の表示

- **アクティブセッション一覧**: すべてのアクティブセッションの表示、再開、キャンセル機能

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

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

```python

python examples/client_example.py

```

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

## ■ メモリ管理

- セッションはメモリ内に保存され、自動削除されません

- 定期的に `/sessions/cleanup` でクリーンアップかサーバの再起動をしてください

## ■ パフォーマンス

- 長時間実行エージェントはサーバーリソースを消費し続けます

- 同時実行セッション数に注意してください

- 不要なセッションは積極的にキャンセルしてください

## ■ セキュリティ

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

## ■ ライセンス

MIT License