docs: document external OCI registry agents as sub-agents

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
 

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:

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
+```
+
+<div class="callout callout-tip">
+<div class="callout-title">💡 Tip
+</div>
+  <p>External sub-agents work with any OCI-compatible registry, not just the Docker Agent Catalog. See <a href="{{ '/concepts/distribution/' | relative_url }}">Agent Distribution</a> for more on registry references.</p>
+
+</div>
+
 ## Example: Development Team
 
 ```yaml

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.                                                                                                               |

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