diff --git a/docs/community/troubleshooting/index.md b/docs/community/troubleshooting/index.md index d239edf1c..9845d4d7b 100644 --- a/docs/community/troubleshooting/index.md +++ b/docs/community/troubleshooting/index.md @@ -136,7 +136,7 @@ docker-agent validates config at startup and reports errors with line numbers. C ### Missing references -- All agents in `sub_agents` must be defined in the `agents` section +- Local agents in `sub_agents` must be defined in the `agents` section (external OCI references like `agentcatalog/pirate` are resolved from registries automatically) - Named model references must exist in the `models` section (or use inline format like `openai/gpt-4o`) - RAG source names referenced by agents must be defined in the `rag` section diff --git a/docs/concepts/distribution/index.md b/docs/concepts/distribution/index.md index 8dbdb4ab3..9c87e7ca1 100644 --- a/docs/concepts/distribution/index.md +++ b/docs/concepts/distribution/index.md @@ -66,6 +66,25 @@ $ docker agent run agentcatalog/pirate $ docker agent run agentcatalog/coder ``` +## Using as Sub-Agents + +Registry agents can be used directly as sub-agents in a multi-agent configuration — no need to define them locally: + +```yaml +agents: + root: + model: openai/gpt-4o + description: Coordinator + instruction: Delegate tasks to the right sub-agent. + sub_agents: + - agentcatalog/pirate # auto-named "pirate" + - my_reviewer:myorg/reviewer # explicitly named "my_reviewer" +``` + +External sub-agents are automatically named after their last path segment. Use the `name:reference` syntax to give them a custom name. + +See [External Sub-Agents]({{ '/concepts/multi-agent/#external-sub-agents-from-registries' | relative_url }}) for details. + ## Using with Aliases Combine OCI references with aliases for convenient access: diff --git a/docs/concepts/multi-agent/index.md b/docs/concepts/multi-agent/index.md index 3aca75526..490df57ff 100644 --- a/docs/concepts/multi-agent/index.md +++ b/docs/concepts/multi-agent/index.md @@ -183,6 +183,42 @@ list_background_agents() view_background_agent(task_id="agent_task_abc123") ``` +## External Sub-Agents from Registries + +Sub-agents don't have to be defined locally — you can reference agents from OCI registries (such as the [Docker Agent Catalog](https://hub.docker.com/u/agentcatalog)) directly in your `sub_agents` list. This lets you compose teams using pre-built, shared agents without duplicating their configuration. + +```yaml +agents: + root: + model: openai/gpt-4o + description: Coordinator that delegates to local and catalog sub-agents + instruction: | + Delegate tasks to the most appropriate sub-agent. + sub_agents: + - local_helper + - agentcatalog/pirate # pulled from registry automatically + + local_helper: + model: openai/gpt-4o + description: A local helper agent for simple tasks + instruction: You are a helpful assistant. +``` + +External sub-agents are automatically named after their last path segment — for example, `agentcatalog/pirate` becomes `pirate`. You can also give them an explicit name using the `name:reference` syntax: + +```yaml + sub_agents: + - my_pirate:agentcatalog/pirate # available as "my_pirate" + - reviewer:docker.io/myorg/review-agent:latest +``` + +
+
💡 Tip +
+

External sub-agents work with any OCI-compatible registry, not just the Docker Agent Catalog. See Agent Distribution for more on registry references.

+ +
+ ## Example: Development Team ```yaml diff --git a/docs/configuration/agents/index.md b/docs/configuration/agents/index.md index ad8b0a8df..495156ceb 100644 --- a/docs/configuration/agents/index.md +++ b/docs/configuration/agents/index.md @@ -17,7 +17,7 @@ agents: model: string # Required: model reference description: string # Required: what this agent does instruction: string # Required: system prompt - sub_agents: [list] # Optional: sub-agent names + sub_agents: [list] # Optional: local or external sub-agent references toolsets: [list] # Optional: tool configurations rag: [list] # Optional: RAG source references fallback: # Optional: fallback config @@ -63,7 +63,7 @@ agents: | `model` | string | ✓ | Model reference. Either inline (`openai/gpt-4o`) or a named model from the `models` section. | | `description` | string | ✓ | Brief description of the agent's purpose. Used by coordinators to decide delegation. | | `instruction` | string | ✓ | System prompt that defines the agent's behavior, personality, and constraints. | -| `sub_agents` | array | ✗ | List of agent names this agent can delegate to. Automatically enables the `transfer_task` tool. | +| `sub_agents` | array | ✗ | List of agent names or external OCI references this agent can delegate to. Supports local agents, registry references (e.g., `agentcatalog/pirate`), and named references (`name:reference`). Automatically enables the `transfer_task` tool. See [External Sub-Agents]({{ '/concepts/multi-agent/#external-sub-agents-from-registries' | relative_url }}). | | `toolsets` | array | ✗ | List of tool configurations. See [Tool Config]({{ '/configuration/tools/' | relative_url }}). | | `fallback` | object | ✗ | Automatic model failover configuration. | | `add_date` | boolean | ✗ | When `true`, injects the current date into the agent's context. | diff --git a/docs/configuration/overview/index.md b/docs/configuration/overview/index.md index 83746ed8e..891d41b67 100644 --- a/docs/configuration/overview/index.md +++ b/docs/configuration/overview/index.md @@ -164,7 +164,7 @@ API keys and secrets are read from environment variables — never stored in con docker-agent validates your configuration at startup: -- All `sub_agents` must reference agents defined in the config +- Local `sub_agents` must reference agents defined in the config (external OCI references like `agentcatalog/pirate` are pulled from registries automatically) - Named model references must exist in the `models` section - Provider names must be valid (`openai`, `anthropic`, `google`, `dmr`, etc.) - Required environment variables (API keys) must be set