API Reference

Base URL#

http://localhost:8005/api/v1

Endpoints#

POST /api/v1/agents#

Create a new agent with a system prompt, tools, and runtime configuration.

Request:

{
  "name": "Visa Inquiry Agent",
  "description": "Handles visa-related questions",
  "system_prompt": "You are a government visa services assistant...",
  "model": "llama-3.3-70b-versatile",
  "max_steps": 10,
  "temperature": 0.3,
  "tools": ["lookup_service", "check_application_status"]
}

Response:

{
  "id": "agt-001",
  "name": "Visa Inquiry Agent",
  "description": "Handles visa-related questions",
  "model": "llama-3.3-70b-versatile",
  "status": "active",
  "created_at": "2024-01-15T10:30:00Z",
  "runs_count": 0,
  "success_rate": 0.0,
  "avg_duration_ms": 0,
  "tools": ["lookup_service", "check_application_status"]
}

GET /api/v1/agents#

List all registered agents.

curl http://localhost:8005/api/v1/agents

Returns an array of agent objects with their current status, run counts, and success rates.

POST /api/v1/agents/{id}/run#

Execute an agent with a given input. The agent enters its reasoning loop, calling tools as needed, and returns the final output.

Request:

{
  "input": "What's the status of my visa application VA-2024-001?",
  "context": {"user_id": "citizen-123"}
}

Response:

{
  "id": "run-001",
  "agent_id": "agt-001",
  "input": "What's the status of my visa application VA-2024-001?",
  "output": "Your visa application VA-2024-001 is currently under review...",
  "status": "completed",
  "steps_count": 3,
  "total_tokens": 450,
  "duration_ms": 1200,
  "started_at": "2024-01-15T10:30:00Z",
  "completed_at": "2024-01-15T10:30:01Z"
}

GET /api/v1/agents/{id}/traces/{run_id}#

Retrieve the full step-by-step execution trace for a specific run. Each step includes the LLM's reasoning, tool calls with parameters, tool results, and the final response.

curl http://localhost:8005/api/v1/agents/agt-001/traces/run-001

GET /api/v1/agents/{id}/metrics#

Returns performance metrics for an agent: total runs, success rate, average duration, average token consumption, and failure breakdown.

curl http://localhost:8005/api/v1/agents/agt-001/metrics

POST /api/v1/playground/chat#

Interactive chat session with an agent. Maintains conversation state across messages within a session.

Request:

{
  "agent_id": "agt-001",
  "message": "What permits do I need for a restaurant?",
  "session_id": "sess-001"
}

Response:

{
  "session_id": "sess-001",
  "agent_id": "agt-001",
  "message": "What permits do I need for a restaurant?",
  "response": "For a restaurant in Abu Dhabi, you need...",
  "run_id": "run-002",
  "steps_count": 4,
  "duration_ms": 2100
}

DELETE /api/v1/agents/{id}#

Delete an agent and all its associated runs and traces.

curl -X DELETE http://localhost:8005/api/v1/agents/agt-001

Environment Variables#

MCP Server#

Agents exposes a Model Context Protocol server at /mcp, enabling integration with AI assistants and development tools that support the MCP specification.