Description API

SGR Agent Core provides a comprehensive REST API that is fully compatible with OpenAI's API format, making it easy to integrate with existing applications.

Base URL

http://localhost:8010

API Documentation

Interactive API documentation (Swagger UI) is available at http://localhost:8010/docs. You can explore all endpoints, test requests, and view request/response schemas directly in your browser.

Authentication

Authentication is not supported by the API. For production deployments, use a reverse proxy with authentication configured.

GET `/health`

Check if the API is running and healthy.

Request:

curl http://localhost:8010/health

Response:

{
  "status": "healthy",
  "service": "SGR Agent Core API"
}

Response Fields:

status (string, literal: "healthy"): Always returns "healthy" when API is operational
service (string): Service name identifier

GET `/v1/models`

Retrieve a list of available agent models. This endpoint returns all agent definitions configured in the system.

Available Models:

sgr_agent - Pure SGR (Schema-Guided Reasoning)
sgr_tool_calling_agent - SGR + Function Calling hybrid
tool_calling_agent - Pure Function Calling

Request:

curl http://localhost:8010/v1/models

Response:

{
  "data": [
    {
      "id": "sgr_agent",
      "object": "model",
      "created": 1234567890,
      "owned_by": "sgr-agent-core"
    },
    {
      "id": "sgr_tool_calling_agent",
      "object": "model",
      "created": 1234567890,
      "owned_by": "sgr-agent-core"
    }
  ],
  "object": "list"
}

Response Fields:

data (array): List of available agent models
id (string): Agent model identifier (matches agent definition name)
object (string, literal: "model"): Object type identifier
created (integer): Timestamp placeholder (OpenAI compatibility)
owned_by (string): Always "sgr-agent-core"
object (string, literal: "list"): Response type identifier

POST `/v1/chat/completions`

Create a chat completion for research tasks. This is the main endpoint for interacting with SGR agents. Creates a new agent instance and starts its execution asynchronously.

Request Body:

{
  "model": "sgr_agent",
  "messages": [
    {
      "role": "user",
      "content": "Research BMW X6 2025 prices in Russia"
    }
  ],
  "stream": true,
  "max_tokens": 1500,
  "temperature": 0.4
}

Request Parameters:

model (string, required, default: "sgr_tool_calling_agent"): Agent type name (e.g., "sgr_agent", "sgr_tool_calling_agent") or existing agent ID for clarification requests
messages (array, required): List of chat messages in OpenAI format (ChatCompletionMessageParam). Supports:
Text messages: {"role": "user", "content": "text"}
Multimodal messages: {"role": "user", "content": [{"type": "text", "text": "..."}, {"type": "image_url", "image_url": {"url": "..."}}]}
System messages: {"role": "system", "content": "..."}
stream (boolean, required, default: true): Must be true - only streaming responses are supported
max_tokens (integer, optional, default: 1500): Maximum number of tokens for generation
temperature (float, optional, default: 0): Generation temperature (0.0-1.0). Lower values make output more deterministic

Special Behavior - Resuming an Agent in Clarification State:

This endpoint supports two ways to resume an agent that is waiting for clarification:

Mode	Trigger	Conversation handling
Stateless (full-context)	Agent ID found anywhere inside `messages` text	Agent's conversation is replaced entirely with the incoming `messages`
Stateful (delta)	Agent ID passed as the `model` field value	Incoming `messages` are appended to the existing conversation

Use the stateless mode when integrating with a standard OpenAI-compatible chat UI that re-sends the full message history on every request. The agent detects its own ID in the message content, overwrites its conversation snapshot, and resumes execution.

Use the stateful mode when your client tracks context itself and only sends new messages as a delta. Pass the agent ID (format: {agent_name}_{uuid}) as the model field value.

Response:

Response Headers:

X-Agent-ID (string): Unique agent identifier (format: {agent_name}_{uuid})
X-Agent-Model (string): Agent model name used
Cache-Control: no-cache
Connection: keep-alive
Content-Type: text/event-stream

Streaming Response Format:

The response is streamed as Server-Sent Events (SSE) with real-time updates. Each event follows OpenAI-compatible format:

data: {"id":"...","object":"chat.completion.chunk","created":...,"model":"sgr_agent","choices":[{"index":0,"delta":{"content":"..."},"finish_reason":null}]}

data: {"id":"...","object":"chat.completion.chunk","created":...,"model":"sgr_agent","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

Error Responses:

400 Bad Request: Invalid model name or malformed request

{
  "detail": "Invalid model 'invalid_model'. Available models: ['sgr_agent', 'sgr_tool_calling_agent']"
}

501 Not Implemented: Non-streaming request (stream must be true)

{
  "detail": "Only streaming responses are supported. Set 'stream=true'"
}

Request:

curl -X POST "http://localhost:8010/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sgr_agent",
    "messages": [{"role": "user", "content": "Research AI market trends"}],
    "stream": true,
    "temperature": 0
  }'

Request with Image (URL):

curl -X POST "http://localhost:8010/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sgr_agent",
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "Analyze this chart and research the trends"},
        {"type": "image_url", "image_url": {"url": "https://example.com/chart.png"}}
      ]
    }],
    "stream": true
  }'

Request with Image (Base64):

curl -X POST "http://localhost:8010/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sgr_agent",
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "What is shown in this image?"},
        {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."}}
      ]
    }],
    "stream": true
  }'

Note: Base64 image URLs longer than 200 characters will be truncated in responses for performance reasons.

GET `/agents`

Get a list of all active agents currently stored in memory. Returns empty list if no agents are active.

Request:

curl http://localhost:8010/agents

Response:

{
  "agents": [
    {
      "agent_id": "sgr_agent_12345-67890-abcdef",
      "task_messages": [
        {
          "role": "user",
          "content": "Research BMW X6 2025 prices"
        }
      ],
      "state": "researching",
      "creation_time": "2025-01-27T12:00:00"
    }
  ],
  "total": 1
}

Response Fields:

agents (array): List of agent items
agent_id (string): Unique agent identifier (format: {agent_name}_{uuid})
task_messages (array): Original task messages in OpenAI format
state (string): Current agent state (see Agent States below)
creation_time (string, ISO 8601): Agent creation timestamp
total (integer): Total number of agents in storage

Agent States:

inited - Agent initialized, ready to start
researching - Agent is actively researching and executing tasks
waiting_for_clarification - Agent needs user clarification to proceed
completed - Research completed successfully
cancelled - Agent execution was cancelled
failed - Agent execution failed
error - Agent execution error occurred

GET `/agents/{agent_id}/state`

Get detailed state information for a specific agent. Returns comprehensive information about agent's current execution state, progress, and context.

Path Parameters:

agent_id (string, required): Unique agent identifier (format: {agent_name}_{uuid})

Request:

curl http://localhost:8010/agents/sgr_agent_12345-67890-abcdef/state

Response:

{
  "agent_id": "sgr_agent_12345-67890-abcdef",
  "task_messages": [
    {
      "role": "user",
      "content": "Research BMW X6 2025 prices"
    }
  ],
  "state": "researching",
  "iteration": 3,
  "searches_used": 2,
  "clarifications_used": 0,
  "sources_count": 5,
  "current_step_reasoning": {
    "action": "web_search",
    "query": "BMW X6 2025 price Russia",
    "reason": "Need current market data"
  },
  "execution_result": null
}

Response Fields:

agent_id (string): Unique agent identifier
task_messages (array): Original task messages in OpenAI format
state (string): Current agent state (see Agent States in GET /agents)
iteration (integer): Current iteration number (starts from 0)
searches_used (integer): Number of web searches performed so far
clarifications_used (integer): Number of clarification requests made
sources_count (integer): Total number of unique sources collected
current_step_reasoning (object | null): Current step reasoning data (structure varies by agent type)
execution_result (string | null): Final execution result if agent completed, null otherwise

Error Responses:

404 Not Found: Agent not found in storage
```
{
  "detail": "Agent not found"
}
```

POST `/agents/{agent_id}/provide_clarification`

Provide clarification to an agent that is waiting for input. Resumes agent execution after receiving clarification messages. This endpoint operates in stateful (delta) mode: the provided messages are appended to the agent's existing conversation history.

Alternative via /v1/chat/completions

If you are using a standard OpenAI-compatible client that re-sends the full message history on each turn, prefer the stateless mode of POST /v1/chat/completions: embed the agent ID anywhere in the message text (the format agent {agent_id} started is already included by the agent itself at startup) and send the full context as messages. The server will detect the ID, replace the agent's conversation with the incoming snapshot, and resume execution.

Path Parameters:

agent_id (string, required): Unique agent identifier (format: {agent_name}_{uuid})

Request Body:

{
  "messages": [
    {
      "role": "user",
      "content": "Focus on luxury models only, price range 5-8 million rubles"
    }
  ]
}

Request Parameters:

messages (array, required): New clarification messages in OpenAI format (ChatCompletionMessageParam). These are appended to the existing conversation — send only the new user replies, not the full history.

Request:

curl -X POST "http://localhost:8010/agents/sgr_agent_12345-67890-abcdef/provide_clarification" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "Focus on luxury models only"}]
  }'

Response:

Response Headers:

X-Agent-ID (string): Unique agent identifier
Cache-Control: no-cache
Connection: keep-alive
Content-Type: text/event-stream

Streaming Response:

Returns a streaming SSE response with continued research after clarification. The agent resumes execution from the point where it requested clarification.

Error Responses:

404 Not Found: Agent not found in storage
```
{
  "detail": "Agent not found"
}
```

400 Bad Request: Agent is not in waiting_for_clarification state

{
  "detail": "Agent is not waiting for clarification"
}

500 Internal Server Error: Error during clarification processing
```
{
  "detail": "Error message"
}
```

DELETE `/agents/{agent_id}`

Cancel a running agent's execution and remove it from storage. If the agent is currently running, it will be cancelled first before removal.

Path Parameters:

agent_id (string, required): Unique agent identifier (format: {agent_name}_{uuid})

Request:

curl -X DELETE "http://localhost:8010/agents/sgr_agent_12345-67890-abcdef"

Response:

{
  "agent_id": "sgr_agent_12345-67890-abcdef",
  "deleted": true,
  "final_state": "cancelled"
}

Response Fields:

agent_id (string): The ID of the deleted agent
deleted (boolean): Always true on successful deletion
final_state (string): Final state of the agent after deletion. Possible values:
"cancelled" - Agent was running and was cancelled
"completed" - Agent was already completed
"failed" - Agent was in failed state
"error" - Agent was in error state
Other states if agent was in a different state

Behavior:

If the agent is currently running, agent.cancel() is called first
The agent's execution task is stopped asynchronously
The agent state is preserved in final_state before removal
The agent is removed from storage after cancellation/deletion
Works for agents in any state (running, completed, failed, error, etc.)

Error Responses:

404 Not Found: Agent not found in storage
```
{
  "detail": "Agent not found"
}
```

Use Cases:

Stop a long-running research task that is no longer needed
Clean up completed agents from storage
Cancel an agent that is stuck or taking too long
Free up resources by removing inactive agents

Description API

Base URL

API Documentation

Authentication

GET /health

GET /v1/models

POST /v1/chat/completions

GET /agents

GET /agents/{agent_id}/state

POST /agents/{agent_id}/provide_clarification

DELETE /agents/{agent_id}

GET `/health`

GET `/v1/models`

POST `/v1/chat/completions`

GET `/agents`

GET `/agents/{agent_id}/state`

POST `/agents/{agent_id}/provide_clarification`

DELETE `/agents/{agent_id}`