REST API

Agentic includes built-in support for exposing your agent via a REST API using FastAPI. This API makes it easy to integrate your agents with web applications, automation tools, or other services.

Starting the API Server

You can start the API server in three ways:

1. Using AgentRunner in code

from agentic.common import Agent, AgentRunner

agent = Agent(name="MyAgent", instructions="You are a helpful assistant.")
AgentRunner(agent).serve()

2. Using the CLI

The more common approach is to use the command-line interface:

agentic serve examples/basic_agent.py

To enable detailed logging:

AGENTIC_DEBUG=all agentic serve examples/basic_agent.py

3. Starting with a custom port

By default, the server runs on port 8086. You can specify a different port:

agentic serve examples/basic_agent.py --port 9000

API Swagger

Working with Events

When building a client for the Agentic API, you'll need to process various events returned by the agent. Here are the key event types:

prompt_started: Indicates the agent has started processing a prompt
chat_output: Text generated by the agent's LLM
tool_call: Agent is calling a tool with specific arguments
tool_result: Result returned from a tool call
tool_error: Error that occurred during a tool call
turn_end: Final result of the request
wait_for_input: Agent is waiting for user input to continue

Each event includes:

type: The event type
agent: Name of the agent that generated the event
depth: Nesting level (0 for top-level agent, 1+ for sub-agents)
payload: Event-specific data

Client Implementation Example

Below is a simple JavaScript client example that processes a request and handles the event stream. See the Next.js Dashboard Docs and Implementation for a more complete implementation example.

async function chatWithAgent(agentName, message) {
  // Start a request
  const response = await fetch(`http://localhost:8086/${agentName}/process`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ prompt: message })
  });

  const { request_id } = await response.json();

  // Create event source to receive events
  const eventSource = new EventSource(`http://localhost:8086/${agentName}/getevents?request_id=${request_id}&stream=true`);

  eventSource.onmessage = (event) => {
    const agentEvent = JSON.parse(event.data);

    switch(agentEvent.type) {
      case 'chat_output':
        console.log(`Agent: ${agentEvent.payload}`);
        break;
      case 'tool_call':
        console.log(`Using tool: ${agentEvent.payload.name}`);
        break;
      case 'wait_for_input':
        // Handle user input required
        eventSource.close();
        const userInput = prompt(agentEvent.payload.message);
        resumeConversation(agentName, request_id, agentEvent.payload.key, userInput);
        break;
      case 'turn_end':
        console.log('Conversation turn complete');
        eventSource.close();
        break;
    }
  };
}

async function resumeConversation(agentName, requestId, key, value) {
  const response = await fetch(`http://localhost:8086/${agentName}/resume`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      continue_result: {
        [key]: value,
        request_id: requestId
      }
    })
  });

  // Continue handling events...
}

API Documentation

You can access the FastAPI-generated OpenAPI documentation at:

http://0.0.0.0:8086/<agent_name>/docs

This interactive documentation allows you to test endpoints directly in your browser.

Supporting multiple users

By default agentic serve will use the single Agent instance that you create in your code to handle all requests. This works well for simple cases.

In a real production application however you may want to support multiple users. In this case each user gets a separate instance of the agent to handle their requests.

Follow these steps to support multiple users:

Instead of using agentic serve, construct the API server and run it manually:

from agentic.api import AgentAPIServer
server = AgentAPIServer(agent_instances=agent_instances, port=port, lookup_user=get_current_user_from_token)
uvicorn.run(server.app, host="0.0.0.0", port=port)

you should pass a callback into the lookup_user parameter. This function takes an auth token and returns the user object based on that token.

Your client should pass the Authorization header and include a JWT or other token to authenticate the user, like:

Authorization: Bearer <token>

In your callback you should lookup the user by the token. For a JWT you might do this:

async def get_current_user_from_token(session_token: str) -> Optional[User]:
    payload = jwt.decode(session_token, SECRET_KEY)
    user = User(
        id=payload.get("sub"),
        email=payload.get("email"),
        name=payload.get("name"),
    )
    return user

The object you return as the "user" is opaque. But the framework will call hash on it and construct and re-use a dedicated instance of your Agent class mapped to that id.