Launching Agents with RESTful APIs

Introduction: Why Expose Agents via APIs?

Think about how you use your favorite apps: checking email on your phone, responding from your laptop, or asking your smart speaker to read messages. Each device talks to the same service through an API . This is the power of decoupling — separating core logic from any single interface so it can be accessed from anywhere. In this course, we'll put three of those factors into practice by building a real API layer around an AI agent. Specifically, this lesson kicks off Factor 11 — Trigger from anywhere, meet users where they are and expands Factor 6 — Launch / Pause / Resume with simple APIs by implementing the launch part. We'll build a FastAPI server that exposes an AI agent through REST endpoints, making it accessible from web browsers, mobile apps, scripts, or any tool that can make HTTP requests.

Project Structure

As we transition from building standalone agent logic to exposing it via a web service, our project structure reflects a clear separation between the API layer and the core logic . You are already familiar with the core directory, which houses the agent's decision-making logic, tools, and models. We now introduce a server directory to handle web requests and a top-level test.py script to simulate a client: text . ├── src/ │ ├── server/ │ │ └── main.py # FastAPI app: /agent/launch and /agent/state/{id} │ └── core/ # Core agent logic (agent, models, tools, prompts, utils) └── test.py # Simple client script that launches + polls state . ├── src/ │ ├── server/ │ │ └── main.py # FastAPI app: /agent/launch and /agent/state/{id} │ └── core/ # Core agent logic (agent, models, tools, prompts, utils) └── test.py # Simple client script that launches + polls state src/core/ : Contains the Agent class and State models you've used in previous lessons. src/server/main.py : This is where you will write your FastAPI code. It imports the agent from core and exposes it through REST endpoints. test.py : A standalone script that uses the requests library to "talk" to your server, allowing you to test the full lifecycle of an agent task. This separation is central to Factor 11 : your agent logic remains independent of how it is triggered — whether it's via a CLI, a web API, a Slack bot, or a cron job. The server directory is just one thin adapter around a stable core.

Setting Up FastAPI

FastAPI is a modern Python web framework designed for building APIs quickly and efficiently. It uses Python type hints to validate data automatically and generates interactive documentation for your endpoints. To get started, you create an instance of the FastAPI application: Python from fastapi import FastAPI, BackgroundTasks, HTTPException # Create the FastAPI application app = FastAPI() from fastapi import FastAPI, BackgroundTasks, HTTPException # Create the FastAPI application app = FastAPI() This single line creates your API application. The app object will be used to define routes using Python decorators. If you were installing FastAPI locally, you would run pip install fastapi uvicorn in your terminal . To start the server locally, you would run: Shell uvicorn src.server.main:app --reload uvicorn src.server.main:app --reload This tells uvicorn to load the app object from your script and serve it, usually on http://localhost:8000 . The --reload flag automatically restarts the server whenever you change your code. On CodeSignal, this environment is already set up for you.

Join the 1M+ learners on CodeSignal

Be a part of our community of 1M+ users who develop and demonstrate their skills on CodeSignal

text

.
├── src/
│   ├── server/
│   │   └── main.py  # FastAPI app: /agent/launch and /agent/state/{id}
│   └── core/        # Core agent logic (agent, models, tools, prompts, utils)
└── test.py          # Simple client script that launches + polls state

Python

from fastapi import FastAPI, BackgroundTasks, HTTPException

# Create the FastAPI application
app = FastAPI()

Shell

uvicorn src.server.main:app --reload

Python

from pydantic import BaseModel

# Define the expected shape of the request body
class LaunchRequest(BaseModel):
    input_prompt: str  # The user's prompt, must be a string

from pydantic import BaseModel

# Define the expected shape of the request body
class LaunchRequest(BaseModel):
    input_prompt: str  # The user's prompt, must be a string

Python

# Import the State model used to track agent progress
from core.models.state import State

# Import the State model used to track agent progress
from core.models.state import State

Python

from typing import Dict

# Store agent states in memory, keyed by their unique id
states: Dict[str, State] = {}

from typing import Dict

# Store agent states in memory, keyed by their unique id
states: Dict[str, State] = {}

Python

from core.agent import Agent

# Create a single agent instance to handle all requests
agent = Agent()

from core.agent import Agent

# Create a single agent instance to handle all requests
agent = Agent()

Python

import uuid

@app.post("/agent/launch", response_model=State)
def agent_launch(payload: LaunchRequest, background_tasks: BackgroundTasks):
    # Build the initial state with a unique id and the user's prompt
    initial_state = State(
        id=str(uuid.uuid4()),  # Generate a unique identifier
        context=[
            {
                "role": "user",
                "content": payload.input_prompt  # The prompt from the request
            }
        ],
        status="running",
        steps=0
    )
    
    # Save the state so it can be retrieved later
    states[initial_state.id] = initial_state
    
    # Schedule the agent to run without blocking the response
    background_tasks.add_task(_run_agent_in_background, initial_state.id)
    
    # Return the initial state right away so the client gets the id
    return initial_state

import uuid

@app.post("/agent/launch", response_model=State)
def agent_launch(payload: LaunchRequest, background_tasks: BackgroundTasks):
    # Build the initial state with a unique id and the user's prompt
    initial_state = State(
        id=str(uuid.uuid4()),  # Generate a unique identifier
        context=[
            {
                "role": "user",
                "content": payload.input_prompt  # The prompt from the request
            }
        ],
        status="running",
        steps=0
    )
    
    # Save the state so it can be retrieved later
    states[initial_state.id] = initial_state
    
    # Schedule the agent to run without blocking the response
    background_tasks.add_task(_run_agent_in_background, initial_state.id)
    
    # Return the initial state right away so the client gets the id
    return initial_state

Python

def _run_agent_in_background(state_id: str):
    # Look up the current state by id
    state = states[state_id]
    
    # Run the agent, which may take many seconds to complete
    state = agent.run(state)
    
    # Save the updated state so the client can retrieve it
    states[state_id] = state

def _run_agent_in_background(state_id: str):
    # Look up the current state by id
    state = states[state_id]
    
    # Run the agent, which may take many seconds to complete
    state = agent.run(state)
    
    # Save the updated state so the client can retrieve it
    states[state_id] = state

Python

@app.get("/agent/state/{state_id}", response_model=State)
def get_state(state_id: str):
    # Return a 404 error if the state id doesn't exist
    if state_id not in states:
        raise HTTPException(status_code=404, detail="State not found")
    
    # Return the current state for this id
    return states[state_id]

@app.get("/agent/state/{state_id}", response_model=State)
def get_state(state_id: str):
    # Return a 404 error if the state id doesn't exist
    if state_id not in states:
        raise HTTPException(status_code=404, detail="State not found")
    
    # Return the current state for this id
    return states[state_id]

Python

import time
import json
import requests

BASE_URL = "http://localhost:8000"

# Send a POST request to launch the agent with a prompt
response = requests.post(
    f"{BASE_URL}/agent/launch",
    json={"input_prompt": "Solve the root of this equation: x^2 - 5x + 6 = 0"}
)

# Parse the response and print the assigned state id
state = response.json()
print(f"Launched agent with ID: {state['id']}")

import time
import json
import requests

BASE_URL = "http://localhost:8000"

# Send a POST request to launch the agent with a prompt
response = requests.post(
    f"{BASE_URL}/agent/launch",
    json={"input_prompt": "Solve the root of this equation: x^2 - 5x + 6 = 0"}
)

# Parse the response and print the assigned state id
state = response.json()
print(f"Launched agent with ID: {state['id']}")

Python

while True:
    # Fetch the latest state from the server
    response = requests.get(f"{BASE_URL}/agent/state/{state['id']}")
    current_state = response.json()

    # Stop polling once the agent has finished
    if current_state['status'] in ["complete", "max_steps_reached", "failed"]:
        print("Final State:")
        print(json.dumps(current_state, indent=2))
        break
    
    # Wait one second before checking again
    time.sleep(1)

while True:
    # Fetch the latest state from the server
    response = requests.get(f"{BASE_URL}/agent/state/{state['id']}")
    current_state = response.json()

    # Stop polling once the agent has finished
    if current_state['status'] in ["complete", "max_steps_reached", "failed"]:
        print("Final State:")
        print(json.dumps(current_state, indent=2))
        break
    
    # Wait one second before checking again
    time.sleep(1)

text

Launched agent with ID: 01c0acc0-b153-4c11-936c-68d5d6e84793
Final State:
{
  "id": "01c0acc0-b153-4c11-936c-68d5d6e84793",
  "steps": 8,
  "status": "complete",
  "context": [
    {
      "role": "user",
      "content": "Solve the root of this equation: x^2 - 5x + 6 = 0"
    },
    {
      "type": "function_call",
      "name": "power",
      "arguments": "{\"base\": -5, \"exponent\": 2}",
      "call_id": "call_XBbnlWkq2CyHWZeL4zaCo5X0"
    },
    ...
    {
      "type": "function_call",
      "name": "final_answer",
      "arguments": "{\"answer\": \"The equation x^2 - 5x + 6 = 0 has roots x = 2 and x = 3.\"}",
      "call_id": "call_UjcLh8OJjJoJ9yB3D9ZWPpV3"
    }
  ],
  "pending_tool_calls": [],
  "error": null,
  "final_answer": "The equation x^2 - 5x + 6 = 0 has roots x = 2 and x = 3."
}

Launched agent with ID: 01c0acc0-b153-4c11-936c-68d5d6e84793
Final State:
{
  "id": "01c0acc0-b153-4c11-936c-68d5d6e84793",
  "steps": 8,
  "status": "complete",
  "context": [
    {
      "role": "user",
      "content": "Solve the root of this equation: x^2 - 5x + 6 = 0"
    },
    {
      "type": "function_call",
      "name": "power",
      "arguments": "{\"base\": -5, \"exponent\": 2}",
      "call_id": "call_XBbnlWkq2CyHWZeL4zaCo5X0"
    },
    ...
    {
      "type": "function_call",
      "name": "final_answer",
      "arguments": "{\"answer\": \"The equation x^2 - 5x + 6 = 0 has roots x = 2 and x = 3.\"}",
      "call_id": "call_UjcLh8OJjJoJ9yB3D9ZWPpV3"
    }
  ],
  "pending_tool_calls": [],
  "error": null,
  "final_answer": "The equation x^2 - 5x + 6 = 0 has roots x = 2 and x = 3."
}

Python

from pydantic import BaseModel

# Define the expected shape of the request body
class LaunchRequest(BaseModel):
    input_prompt: str  # The user's prompt, must be a string

Python

# Import the State model used to track agent progress
from core.models.state import State

Python

from typing import Dict

# Store agent states in memory, keyed by their unique id
states: Dict[str, State] = {}

Python

from core.agent import Agent

# Create a single agent instance to handle all requests
agent = Agent()

Python

import uuid

@app.post("/agent/launch", response_model=State)
def agent_launch(payload: LaunchRequest, background_tasks: BackgroundTasks):
    # Build the initial state with a unique id and the user's prompt
    initial_state = State(
        id=str(uuid.uuid4()),  # Generate a unique identifier
        context=[
            {
                "role": "user",
                "content": payload.input_prompt  # The prompt from the request
            }
        ],
        status="running",
        steps=0
    )
    
    # Save the state so it can be retrieved later
    states[initial_state.id] = initial_state
    
    # Schedule the agent to run without blocking the response
    background_tasks.add_task(_run_agent_in_background, initial_state.id)
    
    # Return the initial state right away so the client gets the id
    return initial_state

Python

def _run_agent_in_background(state_id: str):
    # Look up the current state by id
    state = states[state_id]
    
    # Run the agent, which may take many seconds to complete
    state = agent.run(state)
    
    # Save the updated state so the client can retrieve it
    states[state_id] = state

Python

@app.get("/agent/state/{state_id}", response_model=State)
def get_state(state_id: str):
    # Return a 404 error if the state id doesn't exist
    if state_id not in states:
        raise HTTPException(status_code=404, detail="State not found")
    
    # Return the current state for this id
    return states[state_id]

Python

import time
import json
import requests

BASE_URL = "http://localhost:8000"

# Send a POST request to launch the agent with a prompt
response = requests.post(
    f"{BASE_URL}/agent/launch",
    json={"input_prompt": "Solve the root of this equation: x^2 - 5x + 6 = 0"}
)

# Parse the response and print the assigned state id
state = response.json()
print(f"Launched agent with ID: {state['id']}")

Python

while True:
    # Fetch the latest state from the server
    response = requests.get(f"{BASE_URL}/agent/state/{state['id']}")
    current_state = response.json()

    # Stop polling once the agent has finished
    if current_state['status'] in ["complete", "max_steps_reached", "failed"]:
        print("Final State:")
        print(json.dumps(current_state, indent=2))
        break
    
    # Wait one second before checking again
    time.sleep(1)

text

Launched agent with ID: 01c0acc0-b153-4c11-936c-68d5d6e84793
Final State:
{
  "id": "01c0acc0-b153-4c11-936c-68d5d6e84793",
  "steps": 8,
  "status": "complete",
  "context": [
    {
      "role": "user",
      "content": "Solve the root of this equation: x^2 - 5x + 6 = 0"
    },
    {
      "type": "function_call",
      "name": "power",
      "arguments": "{\"base\": -5, \"exponent\": 2}",
      "call_id": "call_XBbnlWkq2CyHWZeL4zaCo5X0"
    },
    ...
    {
      "type": "function_call",
      "name": "final_answer",
      "arguments": "{\"answer\": \"The equation x^2 - 5x + 6 = 0 has roots x = 2 and x = 3.\"}",
      "call_id": "call_UjcLh8OJjJoJ9yB3D9ZWPpV3"
    }
  ],
  "pending_tool_calls": [],
  "error": null,
  "final_answer": "The equation x^2 - 5x + 6 = 0 has roots x = 2 and x = 3."
}

Introduction: Why Expose Agents via APIs?

Project Structure

Setting Up FastAPI

Join the 1M+ learners on CodeSignal

Defining the Launch Request Model

Understanding the State Model

Managing State with In-Memory Storage

Creating the Agent Instance

Building the Launch Endpoint Structure

Implementing Background Task Execution

Creating the State Retrieval Endpoint

Setting Up the Test Script

Implementing the Polling Loop

Viewing the Complete Output

Summary and What's Next