Skip to Content
API ReferenceEndpointsAgents

Agent Endpoints

Agent execution and management endpoints. Served through the API gateway at http://localhost:8000.

Endpoints

MethodPathDescription
POST/executeExecute an agent pipeline
GET/conversations/{id}/streamStream agent response via SSE

POST /execute

Execute a full agent pipeline synchronously. The agent runs through the complete LangGraph StateGraph: system prompt, memory retrieval, LLM call, tool execution, skill injection, HITL approval, synthesis, and output formatting.

Request:

curl -X POST http://localhost:8000/execute \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_type": "rule_37",
    "user_message": "I need a spacing exception for well API 42-383-12345 on the Smith Ranch lease",
    "conversation_id": "conv-optional-id",
    "context": {}
  }'
FieldTypeRequiredDescription
agent_typestringYesOne of: rule_37, rule_32, compliance_monitor, flaring_monitor
user_messagestringYesThe user’s input message
conversation_idstringNoExisting conversation ID, or auto-generated
contextobjectNoAdditional context to pass to the agent

Response (200):

{
  "conversation_id": "conv-abc123",
  "agent_type": "rule_37",
  "response": "Based on the spacing analysis for well 42-383-12345...",
  "tools_called": ["spacing_calculation", "offset_well_analysis"],
  "skills_injected": ["spacing-calculation"],
  "approval_required": true,
  "token_usage": {
    "prompt_tokens": 4200,
    "completion_tokens": 1800,
    "total_tokens": 6000
  },
  "cost_usd": 0.12
}

GET /conversations/{conversation_id}/stream

Stream agent responses in real-time via Server-Sent Events. See the SSE Events page for the full event type reference.

Request:

curl -N -H "Authorization: Bearer $TOKEN" \
  http://localhost:8000/conversations/conv-abc123/stream

Response: text/event-stream with JSON event objects.

data: {"event_type": "agent_status", "status": "thinking", "node": "system_prompt_node"}
data: {"event_type": "token", "content": "Based on "}
data: {"event_type": "token", "content": "the analysis..."}
data: {"event_type": "done", "final_response": "..."}

The SSE endpoint is the recommended way to interact with agents in production. The synchronous /execute endpoint is useful for testing and batch operations.

Last updated on
AuthConversations