Agent Endpoints

The Agent API provides endpoints for managing agent lifecycle, triggering agent orchestration, streaming agent responses, and configuring agent behavior. These endpoints are the primary interface for the Agentic Workbench and programmatic agent interactions.

Process Message

Sends a message to the agent orchestrator for processing through the multi-agent pipeline.

Property	Value
Method	`POST`
Path	`/api/v1/agents/process`
Auth	JWT required

Request Body

{
  "session_id": "sess-abc123",
  "message": "Show me sales trends for the last 6 months",
  "tenant_id": "acme-corp",
  "user_id": "user-456",
  "agent_config": {
    "provider": "openai",
    "model": "gpt-4",
    "temperature": 0.7,
    "tools_enabled": true
  }
}

Response

{
  "id": "resp-789",
  "content": "Here are the sales trends...",
  "tool_calls": [],
  "tool_results": [],
  "reasoning": "Identified as a time-series analysis query...",
  "requires_approval": false,
  "execution_time_ms": 2450,
  "tokens_used": 1823
}

Stream Agent Response

Opens a Server-Sent Events stream for real-time agent response delivery.

Property	Value
Method	`GET`
Path	`/api/v1/agents/stream/:session_id`
Auth	JWT required
Content-Type	`text/event-stream`

Event Types

Event Type	Description
`text`	Incremental text content from the agent
`tool_call`	Agent is invoking a tool
`tool_result`	Tool execution result
`status`	Agent status update (thinking, executing, complete)
`error`	Error during agent processing

Example SSE Stream

event: status
data: {"type": "status", "content": "thinking"}

event: text
data: {"type": "text", "content": "Analyzing sales data..."}

event: tool_call
data: {"type": "tool_call", "data": {"tool": "sql_generator", "input": "..."}}

event: text
data: {"type": "text", "content": "Based on the query results...", "is_final": true}

List Agents

Returns available agent types and their configurations.

Property	Value
Method	`GET`
Path	`/api/v1/agents`
Auth	JWT required

Response

{
  "agents": [
    {
      "id": "router-agent",
      "type": "router",
      "name": "Router Agent",
      "description": "Routes queries to specialized agents",
      "capabilities": ["intent_classification", "routing"]
    },
    {
      "id": "sql-agent",
      "type": "specialist",
      "name": "SQL Agent",
      "description": "Generates and executes SQL queries",
      "capabilities": ["sql_generation", "query_execution"]
    }
  ]
}

Get Agent Status

Returns the current status of an active agent session.

Property	Value
Method	`GET`
Path	`/api/v1/agents/status/:session_id`
Auth	JWT required

Response

{
  "session_id": "sess-abc123",
  "status": "idle",
  "active_agents": [],
  "message_count": 5,
  "last_activity": "2025-03-15T10:30:00Z"
}

Submit Approval

Submits an approval decision for a human-in-the-loop checkpoint.

Property	Value
Method	`POST`
Path	`/api/v1/agents/approve`
Auth	JWT required

Request Body

{
  "approval_id": "appr-101",
  "session_id": "sess-abc123",
  "decision": "approved",
  "comment": "SQL query looks correct"
}

Response

{
  "success": true,
  "approval_id": "appr-101",
  "status": "approved",
  "resumed": true
}

Text-to-SQL Endpoints Chat Endpoints