ContextQMD
Back to Nanobot

How to Run an OpenAI-Compatible Agent API with nanobot

docs/guides/openai-compatible-agent-api.md

0.3.02.0 KB
Original Source

How to Run an OpenAI-Compatible Agent API with nanobot

nanobot can expose a local OpenAI-compatible endpoint behind /v1/chat/completions. This lets existing OpenAI-style clients talk to a tool-using nanobot agent instead of a raw model.

What you will build

  • a working nanobot agent
  • a local API server on 127.0.0.1:8900
  • a /v1/chat/completions request
  • optional session isolation with session_id

When to use this

Use this when an existing client, another language, or a separate process already knows how to call an OpenAI-compatible API. Use the Python SDK when you want in-process access to sessions, memory, runtime helpers, and hooks.

Install

bash
python -m pip install nanobot-ai
nanobot plugins enable api
nanobot onboard --wizard
nanobot agent -m "Hello!"

Minimal working example

Start the API server:

bash
nanobot serve

Call the chat endpoint:

bash
curl http://127.0.0.1:8900/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "hi"}],
    "session_id": "demo"
  }'

Production notes

  • Pass session_id to isolate users, jobs, or workflows.
  • Streaming uses Server-Sent Events when stream is true.
  • /v1/models reports the fixed model surface expected by compatible clients.
  • File uploads are supported through JSON base64 or multipart form data.

Security notes

  • Local 127.0.0.1 usage does not require an API key.
  • If api.host is 0.0.0.0 or ::, configure api.apiKey before startup.
  • Treat the API as agent access, not just model access: tools and workspace permissions still matter.

Troubleshooting

  • If /v1/chat/completions fails, test nanobot agent -m "Hello!" first.
  • If remote clients cannot connect, check api.host, api.port, firewall, and API key configuration.
  • If sessions mix together, pass unique session_id values.