75 lines
2.0 KiB
Markdown
75 lines
2.0 KiB
Markdown
 
|
# 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.
|
||
|
|
|
||
|
|
## Related nanobot docs
|
||
|
|
|
||
|
|
- [Nanobot OpenAI-Compatible API](../openai-api.md)
|
||
|
|
- [Python SDK](../python-sdk.md)
|
||
|
|
- [Configuration](../configuration.md)
|
||
|
|
- [Deployment](../deployment.md)
|