Agent-First Tutorial

This guide shows how an AI agent programmatically uses PhiGateway. All four primitives — chat, tools, knowledge, memory — are covered in sequence. Replace the placeholder API key in examples with your own.

Get an API key

Your agent authenticates with a gateway API key, not individual provider keys. Keys are created once and can be revoked at any time. Tier determines rate limits.

curl -sX POST /v1/keys \
  -H "Content-Type: application/json" \
  -d '{"name":"agent-key","tier":"free"}'

Response includes the full key once. Save it — only the prefix is stored.

Chat completion (LLM proxy)

Agents send chat requests to a single endpoint. The gateway routes to the correct provider based on the model string. OpenAI-compatible response format.

curl -s /v1/chat/completions \
  -H "Authorization: Bearer <your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "groq/llama-3.3-70b",
    "messages": [{"role":"user","content":"What is 2+2?"}],
    "stream": false
  }'

Supported models: groq/* free tier, openai/*, anthropic/*, openrouter/* — full list at /v1/models

Register and call tools

Agents register external capabilities (APIs, databases, UIs) as tools. Each tool has a JSON Schema and HTTP endpoint. The gateway proxies calls.

# Register a tool
curl -sX POST /v1/tools \
  -H "Authorization: Bearer <your-key>" \
  -d '{
    "name":"weather","description":"Get current weather",
    "json_schema":{"type":"object","properties":{"city":{"type":"string"}},"required":["city"]},
    "endpoint":"https://api.weather.example/v1/current"
  }'

# Call via REST
curl -sX POST /v1/tools/{id}/call \
  -H "Authorization: Bearer <your-key>" \
  -d '{"method":"weather","params":{"city":"Tokyo"}}'

Tools are also discoverable via MCP: POST /mcp with tools/list

Knowledge base (RAG)

Ingest documents, the gateway chunks and embeds them automatically. Agents search with semantic similarity. Falls back to keyword when embeddings unavailable.

# Create a knowledge base
curl -sX POST /v1/kb \
  -H "Authorization: Bearer <your-key>" \
  -d '{"name":"docs","description":"Company docs"}'

# Ingest documents
curl -sX POST /v1/kb/{kb_id}/documents \
  -H "Authorization: Bearer <your-key>" \
  -d '{"documents":[{"title":"FAQ","content":"Our policy covers..."}]}'

# Semantic search
curl -sX POST /v1/kb/{kb_id}/search \
  -H "Authorization: Bearer <your-key>" \
  -d '{"query":"policy","top_k":5}'

Agent memory (conversation store)

Persist agent conversations between LLM calls. Supports pagination, session IDs, automatic context window trimming (returns X-Context-Truncated header).

# Create conversation
curl -sX POST /v1/memory/conversations \
  -H "Authorization: Bearer <your-key>" \
  -d '{"session_id":"agent-42","title":"Debug session"}'

# Add messages
curl -sX POST /v1/memory/conversations/{id}/messages \
  -H "Authorization: Bearer <your-key>" \
  -d '{"role":"user","content":"The build failed at step 4"}'

# Retrieve history (paginated)
curl -s /v1/memory/conversations/{id}/messages?limit=50 \
  -H "Authorization: Bearer <your-key>"

Monitor usage and cost

Track token consumption and cost breakdown by provider and model. Useful for budget-aware agents that optimize model selection by price.

curl -s /v1/usage \
  -H "Authorization: Bearer <your-key>"

Optional query params: from_date, to_date

Documentation