docs: improve search entry pages

2026-07-08 20:56:27 +08:00
parent 941a2541eb
commit f531f1ce38
33 changed files with 2132 additions and 17 deletions
@@ -0,0 +1,75 @@
+# Nanobot Python SDK: Run an AI Agent from Python
+
+This guide shows when to use the Nanobot Python SDK instead of calling a model
+directly. The SDK runs the same agent runtime used by the CLI: model routing,
+tools, workspace access, session history, memory, streaming events, and runtime
+helpers.
+
+## What you will build
+
+- a Python script that creates a `Nanobot`
+- one agent run from code
+- an optional streamed run with tool visibility
+
+## When to use this
+
+Use the Python SDK for notebooks, evals, product backends, local scripts,
+workflow runners, and integrations that need direct access to agent sessions,
+memory, hooks, runtime state, or structured run results.
+
+Use the OpenAI-compatible API instead when another language or process should
+call nanobot over HTTP.
+
+## Install
+
+```bash
+python -m pip install nanobot-ai
+nanobot onboard --wizard
+nanobot agent -m "Hello!"
+```
+
+## Minimal working example
+
+```python
+import asyncio
+
+from nanobot import Nanobot
+
+
+async def main() -> None:
+    async with Nanobot.from_config() as bot:
+        result = await bot.run("List the top-level files in this workspace.")
+    print(result.content)
+
+
+asyncio.run(main())
+```
+
+## Production notes
+
+- Reuse one `Nanobot` instance for related work.
+- Pass `session_key` when a user, job, or eval case needs persistent history.
+- Use `bot.stream(...)` when the caller needs live text, tool, or failure
+  events.
+- Use hooks for audit logs or custom observability.
+
+## Security notes
+
+- The SDK uses the same config, workspace, tools, and secrets as the CLI.
+- Do not run untrusted prompts with broad file or shell access.
+- Keep separate config/workspace paths for separate products or tenants.
+
+## Troubleshooting
+
+- If SDK code fails, first run `nanobot agent -m "Hello!"` in the same
+  environment.
+- Print `bot.runtime.workspace` and `bot.runtime.model` to confirm the expected
+  config loaded.
+- Use explicit `config_path` and `workspace` when scripts run from services.
+
+## Related nanobot docs
+
+- [Nanobot Python SDK](../python-sdk.md)
+- [OpenAI-Compatible API](../openai-api.md)
+- [Configuration](../configuration.md)
+- [Concepts](../concepts.md)