Agency Swarm supports serving your agencies and tools as production-ready HTTP APIs using FastAPI. This enables you to interact with your agents and tools over HTTP, integrate with other services, or connect it to web frontends.

​
Installation

FastAPI integration is an optional installation. To install all required dependencies, run: 
pip install "agency-swarm[fastapi]"

​
Setting Up FastAPI Endpoints

You can expose your agencies and tools as API endpoints using the run_fastapi() function.

​
Example: Create an API endpoint for a single agency

from agency_swarm import Agency, Agent

agent = Agent(
    name="Assistant",
    instructions="You are a helpful assistant."
)

agency = Agency(agent, name="test_agency")

agency.run_fastapi()
Optionally, you can specify following parameters:
  • host (default: "0.0.0.0")
  • port (default: 8000)
  • app_token_env (default: "APP_TOKEN") - Name of the env variable storing app token.
  • return_app (default: False) - If True, will return the FastAPI instead of running the server
  • cors_origins: (default: [”*”])
This will create 2 endpoints for the agency:
  • /test_agency/get_response
  • /test_agency/get_response_stream
Both of these endpoints will accept following input parameters: 
message: str
# Entire chat history containing previous messages across all threads in a form of {'thread_1': ConversationThread, 'thread_2': ConversationThread, ...}
chat_history: dict[str, ConversationThread] = None
recipient_agent: str = None
file_ids: list[str] = None
# Files to download and attach to the agent. Should be provided in a form of a mapping: {"filename_1":"url", "filename_2":"url", ...}
file_urls: dict[str, str] = None
additional_instructions: str = None
Additionally, you will need to provide a bearer token in the authorization if you have "APP_TOKEN" specified (or a differently named variable if you provided app_token_env). If the token is not specified in the env variables, authentication will be disabled.

​
Example: Serving Multiple Agencies and Tools

from agency_swarm import Agency, Agent, function_tool, run_fastapi

# Example tools using agents SDK
@function_tool
def example_tool(example_field: str) -> str:
    """Example tool with input field."""
    return f"Result of ExampleTool operation with {example_field}"

@function_tool
def test_tool(example_field: str) -> str:
    """Test tool with input field."""
    return f"Result of TestTool operation with {example_field}"

# Create agents
agent1 = Agent(name="Assistant1", instructions="You are assistant 1.")
agent2 = Agent(name="Assistant2", instructions="You are assistant 2.")

# Create agencies
agency1 = Agency(agent1, name="test_agency_1")
agency2 = Agency(agent2, name="test_agency_2")

run_fastapi(
    agencies=[agency1, agency2],
    tools=[example_tool, test_tool],
)
This will create 6 following endpoints:
  • /test_agency_1/get_response
  • /test_agency_1/get_response_stream
  • /test_agency_2/get_response
  • /test_agency_2/get_response_stream
  • /tool/ExampleTool (for BaseTools) or /tool/example_tool (for function tools)
  • /tool/TestTool (for BaseTools) or /tool/test_tool (for function tools)
Inputs for the tool endpoints will follow their respective schemas.

​
API Usage Example

You can interact with your agents and tools using HTTP requests. Here’s an example using Python’s requests library: 
import requests

agency_url = "http://127.0.0.1:8000/test_agency_1/get_response"
payload = {
    "message": "Hello",
}

headers = {
    "Authorization": "Bearer 123"  # Replace with your actual token if needed
}

agency_response = requests.post(agency_url, json=payload, headers=headers)
print("Status code:", agency_response.status_code)
print("Response:", agency_response.json())

tool_url = "http://127.0.0.1:8000/tool/example_tool"
payload = {
    "example_field": "test",
}

tool_response = requests.post(tool_url, json=payload, headers=headers)
print("Status code:", tool_response.status_code)
print("Response:", tool_response.json())

​
Endpoint Structure

  • Agency Endpoints: Each agency is served at:
    • /your_agency_name/get_response (POST)
    • /your_agency_name/get_response_stream (POST, streaming responses)
  • Tool Endpoints: Each tool is served at:
    • /tool/ToolClassName (POST) - v0.x
    • /tool/function_name (POST) - v1.x

​
File Attachments (v1.x)

When using the agency endpoints (/{your_agency}/get_response and /{your_agency}/get_response_stream), you can attach files in two ways:
  • Direct inline: .pdf, .jpeg, .jpg, .gif, .png
  • Via file_ids / file_urls (processed, not inline): .c, .cs, .cpp, .csv, .html, .java, .json, .php, .py, .rb, .css, .js, .sh, .ts, .pkl, .tar, .xlsx, .xml, .zip, .doc, .docx, .md, .pptx, .tex, .txt
  • Rejected: .go and any extension not listed above
  • Payload fields: file_ids: string[] OR file_urls: { filename: url }
Behavior with file_urls:
  • The server downloads each URL, uploads it to OpenAI, waits until processed, and uses the resulting File IDs.
  • file_ids_map (shape: { filename: file_id }) is returned in the non‑streaming JSON response of POST /get_response and in the final event: messages SSE payload of POST /get_response_stream.