Connecting External AI Tools to Sagewai

Sagewai exposes an OpenAI-compatible API at /v1/chat/completions and /v1/models. This means any tool that speaks the OpenAI protocol can use your Sagewai agents --- including Claude Code, ChatGPT custom GPTs, Gemini, Cursor, and more.

How It Works

Sagewai's gateway maps each registered agent to a "model" name. When an external tool sends a chat completion request, the gateway routes it to the corresponding Sagewai agent.

External Tool (Claude Code, Cursor, etc.)
    |
    v
POST /v1/chat/completions  { "model": "my-agent", ... }
    |
    v
Sagewai Gateway  -->  resolve "my-agent"  -->  AgentRegistry
    |
    v
UniversalAgent.chat(message)
    |
    v
Response (OpenAI-compatible JSON)

Starting the Gateway

# Start the admin backend (includes gateway)
make dev-native APP=admin

# Or start just the gateway
sagewai admin serve --port 8000

The gateway is available at http://localhost:8000/v1/.

Authentication

Generate an API token:

sagewai token create --agent my-agent --scopes chat

Use it in the Authorization: Bearer <token> header.

Testing with curl

# List available agents (models)
curl http://localhost:8000/v1/models \
  -H "Authorization: Bearer <token>"

# Chat with an agent
curl http://localhost:8000/v1/chat/completions \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "knowledge-agent",
    "messages": [{"role": "user", "content": "What were last week'\''s key decisions?"}]
  }'

Claude Code

Claude Code natively uses the Anthropic API, not OpenAI-compatible endpoints. To access Sagewai agents from Claude Code, use the MCP server approach (see below) or call the gateway from a custom tool:

# In a Claude Code custom tool or script:
import httpx

response = httpx.post(
    "http://localhost:8000/v1/chat/completions",
    headers={"Authorization": "Bearer your-sagewai-token"},
    json={
        "model": "knowledge-agent",
        "messages": [{"role": "user", "content": "What were last week's decisions?"}],
    },
)
print(response.json()["choices"][0]["message"]["content"])

For deeper integration, use the Sagewai MCP Server so agents appear as callable tools directly in Claude Code.

ChatGPT Custom GPT

When creating a Custom GPT, use the Actions feature:

Set the API endpoint to http://your-server:8000/v1/chat/completions
Add the Bearer token authentication
The GPT will be able to query your Sagewai agents

Gemini / Google AI Studio

Use the OpenAI-compatible client:

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="your-sagewai-token",
)

response = client.chat.completions.create(
    model="knowledge-agent",
    messages=[{"role": "user", "content": "Summarize our Q1 results"}],
)
print(response.choices[0].message.content)

Cursor IDE

In Cursor settings, add a custom model provider:

Base URL: http://localhost:8000/v1
API Key: your Sagewai token
Model Name: the agent name from /v1/models

Cursor will then use your Sagewai agent for code completions and chat.

LiteLLM Proxy

If you use LiteLLM as a unified proxy, add Sagewai as a provider:

model_list:
  - model_name: sagewai/knowledge-agent
    litellm_params:
      model: openai/knowledge-agent
      api_base: http://localhost:8000/v1
      api_key: your-sagewai-token

Python OpenAI SDK

Any application using the OpenAI Python SDK can connect directly:

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="your-sagewai-token",
)

# List all available agents
models = client.models.list()
for m in models.data:
    print(m.id)  # e.g. "knowledge-agent", "research-agent"

# Chat with an agent
response = client.chat.completions.create(
    model="research-agent",
    messages=[
        {"role": "system", "content": "You are a research assistant."},
        {"role": "user", "content": "Find recent papers on transformer architectures"},
    ],
)
print(response.choices[0].message.content)

# Streaming
stream = client.chat.completions.create(
    model="research-agent",
    messages=[{"role": "user", "content": "Explain attention mechanisms"}],
    stream=True,
)
for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

MCP Server (for Claude Code and Cursor)

For deeper integration, use the Sagewai MCP server which exposes agents as tools rather than chat models. This allows Claude Code to invoke specific Sagewai agents as part of its tool-calling workflow.

from sagewai.mcp.server import McpServer

server = McpServer(name="sagewai-tools")

# Register agents as MCP tools
server.register_agent(knowledge_agent)
server.register_agent(research_agent)

# Start the server
await server.serve_stdio()

Available Endpoints

Endpoint	Method	Description
`/v1/models`	GET	List all registered agents
`/v1/chat/completions`	POST	Chat with an agent
`/v1/chat/completions` (stream)	POST	Streaming chat (`stream: true`)

Troubleshooting

"Connection refused"

Ensure the gateway is running:

sagewai admin serve
# or
make dev-native APP=admin

"401 Unauthorized"

Check your API token:

sagewai token list

Agent not appearing in /v1/models

The agent must be registered in the agent registry. Verify with:

sagewai agent list

Streaming not working

Ensure you pass "stream": true in the request body. The gateway supports Server-Sent Events (SSE) for streaming responses.

Next Steps

Your First Agent --- Build an agent to expose via the gateway
Admin Panel --- Monitor agent usage and costs
Tools and MCP --- Expose agents as MCP tools
REST API Reference --- Full API documentation