Agent

​

Overview

• Advanced reasoning and planning
• Function/tool calling
• Multi-step problem solving
• External API integration
• Streaming or non-streaming responses

​

Use cases

• API integration (weather, search, databases)
• Multi-step task planning
• Data retrieval and manipulation
• External system interaction
• Complex reasoning with tools

​

Model details

• Model: Kimi K2 Thinking (via Fireworks)
• Advanced reasoning capabilities
• Native tool calling support
• Caller-executed tools pattern

​

Request example

curl -X POST "https://api.incredible.one/v1/agent" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "What is the weather in San Francisco?"}
    ],
    "system_prompt": "You are a helpful assistant with access to tools.",
    "tools": [
      {
        "name": "get_weather",
        "description": "Get weather information for a location",
        "input_schema": {
          "type": "object",
          "properties": {
            "location": {"type": "string", "description": "City name"}
          },
          "required": ["location"]
        }
      }
    ]
  }'

​

Request Body

• messages array (required) — Conversation history with user and assistant messages
  • role string — Either "user" or "assistant"
  • content string — Message content
• tools array (required) — List of tool definitions available to the agent
  • name string — Tool name (should be descriptive)
  • description string — What the tool does
  • input_schema object — JSON schema defining tool inputs
• system_prompt string (optional) — System prompt to guide the agent (default: “You are a helpful assistant with access to tools.”)
• stream boolean (optional) — Enable streaming response via Server-Sent Events (default: false)

​

Response

​

Non-streaming (default)

{
  "success": true,
  "response": "I'll check the weather in San Francisco for you.",
  "tool_calls": [
    {
      "id": "call_123",
      "name": "get_weather",
      "inputs": {
        "location": "San Francisco"
      }
    }
  ]
}

{
  "success": true,
  "response": "I'm ready to help! Please let me know what you need.",
  "tool_calls": null
}

​

Streaming (stream=true)

data: {"thinking": "The user wants weather information..."}
data: {"content": "I'll check"}
data: {"content": " the weather"}
data: {"tool_call": {"id": "call_123", "name": "get_weather", "inputs": {"location": "San Francisco"}}}
data: {"tokens": 245}
data: {"done": true}

​

Tool execution pattern

1. Agent request → Returns tool calls
2. Caller executes → Run the tools in your code
3. Provide results → Send results back in next request as assistant message
4. Agent responds → Uses tool results to answer

# Step 1: Agent decides to call tool
response1 = call_agent({
    "messages": [{"role": "user", "content": "Weather in SF?"}],
    "tools": [weather_tool]
})
# Returns: tool_calls=[{name: "get_weather", inputs: {location: "SF"}}]

# Step 2: Execute tool
weather_result = get_weather("SF")

# Step 3: Provide result back
response2 = call_agent({
    "messages": [
        {"role": "user", "content": "Weather in SF?"},
        {"role": "assistant", "content": f"Tool result: {weather_result}"}
    ],
    "tools": [weather_tool]
})
# Returns: response="The weather in SF is sunny and 72°F"

​

vs Other Endpoints

​

Next steps

• Auto-executing tools: Chat Completion
• Simple conversations: Conversation
• Available models: Models