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.