diff --git a/docs/_data/nav.yml b/docs/_data/nav.yml index 83bf85bf1..f8d4bc107 100644 --- a/docs/_data/nav.yml +++ b/docs/_data/nav.yml @@ -53,6 +53,8 @@ url: /tools/todo/ - title: Memory url: /tools/memory/ + - title: Tasks + url: /tools/tasks/ - title: Fetch url: /tools/fetch/ - title: Script @@ -69,6 +71,8 @@ url: /tools/background-agents/ - title: Handoff url: /tools/handoff/ + - title: Model Picker + url: /tools/model-picker/ - title: OpenAPI url: /tools/openapi/ - title: A2A diff --git a/docs/community/troubleshooting/index.md b/docs/community/troubleshooting/index.md index cd9bf71e9..f5f967803 100644 --- a/docs/community/troubleshooting/index.md +++ b/docs/community/troubleshooting/index.md @@ -79,9 +79,14 @@ Each model provider requires its own API key as an environment variable: | ------------- | --------------------------------------------------- | | OpenAI | `OPENAI_API_KEY` | | Anthropic | `ANTHROPIC_API_KEY` | -| Google Gemini | `GOOGLE_API_KEY` | +| Google Gemini | `GOOGLE_API_KEY` or `GEMINI_API_KEY` | | Mistral | `MISTRAL_API_KEY` | | xAI | `XAI_API_KEY` | +| Nebius | `NEBIUS_API_KEY` | +| MiniMax | `MINIMAX_API_KEY` | +| Requesty | `REQUESTY_API_KEY` | +| GitHub Copilot | `GITHUB_TOKEN` (PAT with `copilot` scope) | +| Azure OpenAI | `AZURE_API_KEY` (override with `token_key`) | | AWS Bedrock | `AWS_BEARER_TOKEN_BEDROCK` or AWS credentials chain | ```bash @@ -165,7 +170,7 @@ docker-agent validates config at startup and reports errors with line numbers. C ### Port conflicts -When docker-agent as an API server or MCP server, ensure the port is not already in use: +When running docker-agent as an API server or MCP server, ensure the port is not already in use: ```bash # Check if port 8080 is in use @@ -231,16 +236,16 @@ $ docker agent share pull docker.io/username/agent:latest When reviewing debug logs, search for these key patterns: -| Log Pattern | What It Indicates | -| --------------------------- | ------------------------------------------------------------------------------ | ---------------- | -| `"Starting runtime stream"` | Agent execution beginning | -| `"Tool call"` | A tool is being executed | -| `"Tool call result"` | Tool execution completed | -| `"Stream stopped"` | Agent finished processing | +| Log Pattern | What It Indicates | +| --------------------------- | ------------------------------------------------------------------------------------------------ | +| `"Starting runtime stream"` | Agent execution beginning | +| `"Tool call"` | A tool is being executed | +| `"Tool call result"` | Tool execution completed | +| `"Stream stopped"` | Agent finished processing | | `HTTP 429` | Rate limiting — consider adding a [fallback model]({{ '/configuration/agents/' | relative_url }}) | -| `context canceled` | Operation was interrupted (timeout or user cancel) | -| `[RAG Manager]` | RAG retrieval operations | -| `[Reranker]` | Reranking operations | +| `context canceled` | Operation was interrupted (timeout or user cancel) | +| `[RAG Manager]` | RAG retrieval operations | +| `[Reranker]` | Reranking operations |
⚠️ Still stuck? diff --git a/docs/concepts/models/index.md b/docs/concepts/models/index.md index 9691e3073..9e312785f 100644 --- a/docs/concepts/models/index.md +++ b/docs/concepts/models/index.md @@ -57,9 +57,9 @@ Named models let you configure temperature, token limits, thinking budgets, and | Nebius | `nebius` | Open-source and specialised models | `NEBIUS_API_KEY` | | MiniMax | `minimax` | MiniMax models | `MINIMAX_API_KEY` | | Requesty | `requesty` | Multi-provider gateway | `REQUESTY_API_KEY` | -| Azure OpenAI | `azure` | gpt-4o, gpt-5 on Azure | `AZURE_OPENAI_API_KEY` + `base_url` | +| Azure OpenAI | `azure` | gpt-4o, gpt-5 on Azure | `AZURE_API_KEY` + `base_url` | | Ollama | `ollama` | Any local Ollama model | None (local; optional `base_url`) | -| GitHub Copilot | `github-copilot` | Copilot-hosted OpenAI/Anthropic | GitHub CLI auth (`gh auth login`) | +| GitHub Copilot | `github-copilot` | Copilot-hosted OpenAI/Anthropic | `GITHUB_TOKEN` (PAT with `copilot`) | See the [Model Providers]({{ '/providers/overview/' | relative_url }}) section for detailed configuration guides. diff --git a/docs/features/cli/index.md b/docs/features/cli/index.md index e9b6cf7d2..fe578ecac 100644 --- a/docs/features/cli/index.md +++ b/docs/features/cli/index.md @@ -35,6 +35,7 @@ $ docker agent run [config] [message...] [flags] | `--prompt-file ` | Include file contents as additional system context (repeatable) | | `--attach ` | Attach an image file to the initial message | | `--dry-run` | Initialize the agent without executing anything (useful for validating a config) | +| `--remote ` | Use a remote runtime at the given address instead of running the agent locally | | `--lean` | Use a simplified TUI with minimal chrome | | `--json` | Output results as newline-delimited JSON (use with `--exec`) | | `--hide-tool-calls` | Hide tool calls in the output | @@ -42,11 +43,17 @@ $ docker agent run [config] [message...] [flags] | `--sandbox` | Run the agent inside a Docker sandbox (see [Sandbox]({{ '/configuration/sandbox/' | relative_url }})) | | `--template ` | Template image for the sandbox (default: `docker/sandbox-templates:docker-agent`) | | `--sbx` | Prefer the `sbx` CLI backend when available (default `true`; set `--sbx=false` to force `docker sandbox`) | +| `--working-dir ` | Set the working directory for the session (applies to tools and relative paths) | +| `--env-from-file ` | Load environment variables from file (repeatable) | +| `--code-mode-tools` | Provide a single tool to call other tools via JavaScript (forces code-mode tools globally) | +| `--models-gateway ` | Route model traffic through a gateway. Also reads `DOCKER_AGENT_MODELS_GATEWAY` env var. | | `--hook-pre-tool-use ` | Add a pre-tool-use hook command (repeatable). See [Hooks]({{ '/configuration/hooks/' | relative_url }}). | | `--hook-post-tool-use ` | Add a post-tool-use hook command (repeatable) | | `--hook-session-start ` | Add a session-start hook command (repeatable) | | `--hook-session-end ` | Add a session-end hook command (repeatable) | | `--hook-on-user-input ` | Add an on-user-input hook command (repeatable) | +| `--fake ` | Replay AI responses from a cassette file (for testing). Mutually exclusive with `--record`. | +| `--record [path]` | Record AI API interactions to a cassette file (auto-generates filename if no path given) | | `-d, --debug` | Enable debug logging | | `--log-file ` | Custom debug log location | | `-o, --otel` | Enable OpenTelemetry tracing | @@ -176,6 +183,40 @@ $ docker agent serve acp agent.yaml See [ACP]({{ '/features/acp/' | relative_url }}) for details on the Agent Client Protocol. +### `docker agent serve chat` + +Start an HTTP server that exposes one or more agents through an **OpenAI-compatible Chat Completions API** at `/v1/chat/completions` and `/v1/models`. This lets any tool that already speaks the OpenAI protocol — for example [Open WebUI](https://github.com/open-webui/open-webui), `curl`, the OpenAI Python SDK, or LangChain — drive a docker-agent agent without any custom integration. + +```bash +$ docker agent serve chat [config] [flags] +``` + +| Flag | Default | Description | +| ----------------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------- | +| `-a, --agent ` | (all agents) | Name of the agent to expose. If omitted, every agent in the config is exposed as a separate model. | +| `-l, --listen ` | `127.0.0.1:8083` | Address to listen on. | +| `--cors-origin ` | (none) | Allowed CORS origin (e.g. `https://example.com`). Empty disables CORS. | +| `--api-key ` | (none) | Required Bearer token clients must present (`Authorization: Bearer `). Empty disables auth. | +| `--api-key-env ` | (none) | Read the API key from this environment variable instead of the command line. | +| `--max-request-size ` | `1048576` (1 MiB) | Maximum request body size. | +| `--request-timeout ` | `5m` | Per-request timeout (covers model + tool calls + streaming). | +| `--conversations-max ` | `0` | Cache up to N conversations server-side, keyed by `X-Conversation-Id`. `0` disables — clients must resend history. | +| `--conversation-ttl ` | `30m` | Idle TTL after which a cached conversation is evicted. | +| `--max-idle-runtimes ` | `4` | Maximum number of idle runtimes pooled per agent. `0` disables pooling. | + +```bash +# Examples +$ docker agent serve chat agent.yaml +$ docker agent serve chat ./team.yaml --agent reviewer +$ docker agent serve chat agentcatalog/pirate --listen 127.0.0.1:9090 +$ docker agent serve chat agent.yaml --api-key-env CHAT_BEARER_TOKEN + +# Drive it from any OpenAI-compatible client +$ curl http://127.0.0.1:8083/v1/chat/completions \ + -H 'Content-Type: application/json' \ + -d '{"model": "root", "messages": [{"role": "user", "content": "hello"}]}' +``` + ### `docker agent share push` / `docker agent share pull` Share agents via OCI registries. @@ -204,6 +245,16 @@ $ docker agent eval agent.yaml --only "auth*" # Only run matching eva $ docker agent eval agent.yaml --repeat 5 # Repeat each eval 5 times ``` +### `docker agent version` + +Print the version and commit hash for your `docker-agent` install. + +```bash +$ docker agent version +docker agent version v1.54.0 +Commit: 1737035c +``` + ### `docker agent alias` Manage agent aliases for quick access. @@ -262,12 +313,17 @@ Run an alias with: docker agent run ## Global Flags -| Flag | Description | -| ------------------------- | ------------------------------------------------------------ | -| `-d, --debug` | Enable debug logging (default: `~/.cagent/cagent.debug.log`) | -| `--log-file <path>` | Custom debug log location | -| `-o, --otel` | Enable OpenTelemetry tracing | -| `--help` | Show help for any command | +These flags are available on every `docker agent` command: + +| Flag | Description | +| ------------------------- | -------------------------------------------------------------------------------------- | +| `-d, --debug` | Enable debug logging (default location: `~/.cagent/cagent.debug.log`) | +| `--log-file ` | Custom debug log location (only used with `--debug`) | +| `-o, --otel` | Enable OpenTelemetry tracing | +| `--cache-dir ` | Override the cache directory (default: `~/Library/Caches/cagent` on macOS) | +| `--config-dir ` | Override the config directory (default: `~/.config/cagent`) | +| `--data-dir ` | Override the data directory (default: `~/.cagent`) | +| `--help` | Show help for any command | ## Agent References diff --git a/docs/providers/openai/index.md b/docs/providers/openai/index.md index de7a7c307..86a13f1c5 100644 --- a/docs/providers/openai/index.md +++ b/docs/providers/openai/index.md @@ -106,4 +106,4 @@ models: ### Example -See [`examples/websocket_transport.yaml`]({{ '/examples/websocket_transport/' | relative_url }}) for a complete example. +See [`examples/websocket_transport.yaml`](https://github.com/docker/docker-agent/blob/main/examples/websocket_transport.yaml) for a complete example. diff --git a/docs/providers/overview/index.md b/docs/providers/overview/index.md index 06ec4538f..afcbcb96d 100644 --- a/docs/providers/overview/index.md +++ b/docs/providers/overview/index.md @@ -64,9 +64,9 @@ docker-agent also includes built-in aliases for these providers: | Nebius | `nebius` | `NEBIUS_API_KEY` | | MiniMax | `minimax` | `MINIMAX_API_KEY` | | Requesty | `requesty` | `REQUESTY_API_KEY` | -| Azure OpenAI | `azure` | `AZURE_OPENAI_API_KEY` + `base_url` | +| Azure OpenAI | `azure` | `AZURE_API_KEY` + `base_url` | | Ollama | `ollama` | None (local; optional `base_url`) | -| GitHub Copilot | `github-copilot` | GitHub CLI auth (`gh auth login`) | +| GitHub Copilot | `github-copilot` | `GITHUB_TOKEN` (PAT with `copilot` scope) | ```bash # Use built-in providers inline