iTranslated by AI
Building an API-Enabled Multi-Agent Environment with Claude Agent SDK and FastAPI
1. Introduction
In this article, I built a "Multi-AI Agent Environment executable via API" by combining Claude Agent SDK and FastAPI.
By combining Claude Agent SDK and FastAPI, the following can be achieved:
- Request tasks to the agent via HTTP
- Manage agent execution status and cancellation operations via API
- Make it easier to use from other systems and frontends
The project I created is available on GitHub.
Also, the content of this article assumes the following:
■ FastAPI
FastAPI is frequently used for building API servers in Python.
It is an effective framework for cases like this, where AI agents are executed asynchronously.
■ Claude Agent SDK
Claude Agent SDK is a software development kit for building AI agents developed by Anthropic.
While Claude Code executes AI agents on the CLI, Claude Agent SDK allows you to define and execute AI agents within your code.
2. The APIs Implemented This Time
The APIs implemented this time are as follows:
| Endpoint | Method | Description |
|---|---|---|
/execute/ |
POST | Start/Resume a new agent session |
/status/{session_id} |
GET | Get session status, message history, and results |
/cancel/{session_id} |
POST | Interrupt a running session |
/sessions/ |
GET | Get detailed information for all sessions |
/sessions/cleanup |
DELETE | Delete old sessions |
For example, when executing the /execute/ endpoint, sending a request like the one below will start a new agent.
curl -X POST "http://localhost:8000/execute/" \
-H "Content-Type: application/json" \
-d '{
"prompt": "I am is0383kk. Please introduce yourself.",
"model": "us.anthropic.claude-3-5-sonnet-20241022-v1:0",
"max_turns": 10
}'
The returned response will look like this:
Since it is an asynchronous execution, the response at this point does not include the execution result message.
{
"session_id": "XXXXXX",
"status": "running",
"message": "Session XXXXXX started successfully"
}
To retrieve the current status of the execution, you can run the following API:
curl "http://localhost:8000/status/XXXXXX"
■ Session Management Mechanism
In order to turn agent execution into an API, each agent's execution is managed as a "session."
In this implementation, agent sessions are managed with the following statuses:
-
pending: Agent is initializing -
running: Agent is currently executing -
completed: Successfully finished -
error: An exception occurred -
cancelled: Cancelled by the user
■ Basic Policy for Agent Execution
I extended the official sample provided to allow for API execution.
In Claude-Agent-SDK, you can execute an AI agent by using the prompt and options specify-able in ClaudeAgentOptions as arguments to the query method, as shown below.
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
options = ClaudeAgentOptions(
system_prompt="You are an expert Python developer",
permission_mode='acceptEdits',
cwd="/home/user/project"
)
async for message in query(
prompt="Create a Python web server",
options=options
):
print(message)
asyncio.run(main())
Building on the above, I utilized FastAPI's asynchronous features to execute the agent in the background.
When executing an agent, a uuid is issued as the session ID.
@app.post("/execute/", response_model=ExecuteResponse)
async def execute_agent(request: ExecuteRequest):
session_id = str(uuid.uuid4())
# Create session information
session_info = SessionInfo(
session_id=session_id,
status="pending",
prompt=request.prompt,
options=request.to_claude_options()
)
# Execute as a background task
task = asyncio.create_task(run_agent_session(session_info))
session_info.task = task
# Register in session management
await session_manager.add_session(session_info)
return ExecuteResponse(
session_id=session_id,
status="pending",
message=f"Session {session_id} started successfully"
)
When resuming a session while maintaining its state,
ClaudeAgentOptions has an option called resume. By specifying the session ID (uuid) you want to keep there, you can execute the agent while maintaining the conversation history.
3. Trying it out from the Frontend
Now, let's try executing the following implemented APIs from the UI.
-
/execute/: Start/resume a new agent session -
/status/{session_id}: Get session status, message history, and results -
/cancel/{session_id}: Interrupt a running session
■ Prerequisites
This article assumes the following:
- Python 3.8 or higher
- Claude Code is available
I have prepared a requirements.txt, so please install the libraries.
pip install -r requirements.txt
Once ready, start the FastAPI server with the following command:
$ python main.py
INFO: Started server process [17844]
INFO: Waiting for application startup.
INFO: Application startup complete.
INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
I had (Claude Code) prepare a UI for verification.
Open index.html in your browser, and you're all set.
■ Executing the Agent
With the FastAPI server running, you can enter a prompt and click the "Execute Agent" (エージェントを実行) button to run it.
You can check the execution status by clicking the "Check Status" (状態を確認) button to see the response.
■ Re-executing the Agent While Maintaining the Session
By specifying a prompt and a session ID, you can execute the agent while maintaining the session state.
■ Interrupting a Session
You can interrupt a running agent process using the "Cancel Session" (セッションをキャンセル) button.
4. Conclusion
Recently, I feel the trend is shifting from using AI agents for AI-driven development to building and operating/providing AI agents ourselves.
Previously, the focus was on "how to use the models," but from now on, I think the important part will be "what kind of agents to build and how to integrate them."
The repository I created this time is relatively easy to run, so please try running it locally!
Discussion