Agent Endpoints

GET /api/agents

List all defined agents (public).

Response 200:

{
  "data": [
    {
      "id": "uuid",
      "name": "Research Assistant",
      "description": "Searches the web and summarizes results",
      "provider": "openai",
      "model": "gpt-4o",
      "tools": ["web_search", "calculate"],
      "createdAt": "2026-03-06T12:00:00.000Z"
    }
  ]
}

---

GET /api/agents/tools

List all available tools.

Response 200:

{
  "data": [
    {
      "name": "calculate",
      "description": "Safely evaluate a mathematical expression...",
      "parameters": {
        "expression": { "type": "string", "description": "A math expression" }
      },
      "required": ["expression"]
    }
  ]
}

---

POST /api/agents/:id/run

Run an agent with a task input.

Request Body:

{
  "input": "What is 18% tip on a $47.50 bill?"
}

Response 200:

{
  "data": {
    "agentId": "uuid",
    "agentName": "Math Helper",
    "input": "What is 18% tip on a $47.50 bill?",
    "output": "The 18% tip on a $47.50 bill is $8.55.",
    "steps": [
      {
        "type": "thinking",
        "content": "I need to calculate 18% of 47.50",
        "iteration": 1
      },
      {
        "type": "tool_call",
        "tool": "calculate",
        "args": { "expression": "47.50 * 0.18" },
        "iteration": 1
      },
      {
        "type": "tool_result",
        "tool": "calculate",
        "result": "{\"expression\":\"47.50 * 0.18\",\"result\":8.55}",
        "iteration": 1
      },
      {
        "type": "final_answer",
        "content": "The 18% tip on a $47.50 bill is $8.55.",
        "iteration": 2
      }
    ],
    "usage": {
      "prompt_tokens": 320,
      "completion_tokens": 85
    }
  }
}

Errors:

Code	Reason
400	Missing or empty input
404	Agent not found
500	LLM provider error