Calling Router from Any Language

API Overview

Router exposes a FastAPI REST server. The base URL is https://pyckle-agent.fly.dev for the hosted version, or your self-hosted URL if you deployed elsewhere. All endpoints accept and return JSON.

The /agent/run Endpoint

This is the main endpoint. POST a message and get a response.

Request fields

• message (required): Your question or instruction
• tools (optional, bool, default true): Whether to use the MCP tool loop
• model (optional): Override model selection (e.g. "gpt-4o", "claude-3-5-sonnet-20241022")
• model_tier (optional): "fast", "balanced", or "powerful" — routing hint
• reset_history (optional, bool): Clear conversation history before this message
• max_tokens (optional): Max tokens in response
• temperature (optional): 0.0–1.0

Response fields

• response: The agent's answer
• model_used: Which model actually handled the request

curl Examples

# Basic question with tool loop enabled
curl -X POST https://pyckle-agent.fly.dev/agent/run \
  -H "Content-Type: application/json" \
  -d '{"message": "Where is authentication handled?", "tools": true}'

# Fast response, no tools
curl -X POST https://pyckle-agent.fly.dev/agent/run \
  -H "Content-Type: application/json" \
  -d '{"message": "What does search_code do?", "tools": false, "model_tier": "fast"}'

# Check agent health
curl https://pyckle-agent.fly.dev/health

Python Example

import httpx

AGENT_URL = "https://pyckle-agent.fly.dev"

def ask_agent(question: str, use_tools: bool = True) -> str:
    resp = httpx.post(
        f"{AGENT_URL}/agent/run",
        json={"message": question, "tools": use_tools},
        timeout=60,
    )
    resp.raise_for_status()
    return resp.json()["response"]

answer = ask_agent("Why does the payment flow fail with expired sessions?")
print(answer)

JavaScript / fetch Example

async function askAgent(question, useTools = true) {
  const response = await fetch('https://pyckle-agent.fly.dev/agent/run', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ message: question, tools: useTools }),
    signal: AbortSignal.timeout(60000),
  });
  const data = await response.json();
  return data.response;
}

const answer = await askAgent('Where is rate limiting implemented?');
console.log(answer);

Managing Conversation History

The agent maintains conversation history across calls by default. To start a fresh conversation:

# Reset via API
curl -X POST https://pyckle-agent.fly.dev/agent/reset

# Or pass reset_history in the run request
curl -X POST https://pyckle-agent.fly.dev/agent/run \
  -H "Content-Type: application/json" \
  -d '{"message": "Start a new topic.", "reset_history": true}'

List Available Models

curl https://pyckle-agent.fly.dev/agent/models

Returns the list of configured providers and their models. Only providers with API keys set are available.