Duckie as an External Subagent

Use Duckie as an external subagent when a customer-owned orchestration agent should keep ownership of the overall workflow, but Duckie should handle a focused support task such as searching knowledge, summarizing context, classifying a request, or drafting a customer-safe answer. This pattern is intentionally small: the customer’s agent sends Duckie a task, Duckie runs a specialized agent, and Duckie sends the result back to the customer’s system.

Example Flow

Custom webhook deployments accept the request and process it asynchronously. If the orchestrator needs the result, have the Duckie agent call a custom tool configured with a fixed callback API and a correlation ID rather than expecting the webhook response to include the final answer.

When to Use This Pattern

Use Duckie as an external subagent when:

You already have a primary orchestration agent outside Duckie.
Duckie should own a narrow support capability, not the whole customer journey. For the Duckie-native version of this pattern, see Sub-Agents.
The task benefits from Duckie knowledge search, runbooks, guidelines, guardrails, or support tools.
Your orchestrator can continue after receiving an async callback from Duckie.

Good first tasks include:

Search internal support docs and return a sourced answer.
Classify a customer request into your support taxonomy.
Summarize a ticket, conversation, or account record.
Draft a customer-facing response for the orchestrator to review or send.
Check policy eligibility and return a recommendation.

What to Build

Component	Purpose
Customer-owned orchestration agent	Owns the parent workflow and decides when Duckie should be called.
Custom webhook deployment	Receives the task payload and starts the Duckie agent.
Focused Duckie agent	Performs one narrow task, such as search or classification.
Custom callback tool	Sends the final result back to your orchestrator API.
Correlation ID	Connects the Duckie result to the parent orchestration task.

Request Shape

Send the task to a Duckie custom webhook as JSON.

{
  "event": {
    "id": "evt_123",
    "type": "subagent.search.requested"
  },
  "task": {
    "id": "task_456",
    "type": "knowledge_search",
    "question": "What is our refund policy for annual plans?"
  },
  "context": {
    "customer_id": "cus_789",
    "plan": "enterprise",
    "region": "us"
  }
}

Map the payload into:

Duckie field	Example mapping
Event ID	`$.event.id`
Ticket ID	`$.task.id`
Ticket Title	`Duckie subagent task {{task.id}}`
Message Body	`{{task.question}}`
Run Metadata	`task_id: $.task.id`, `task_type: $.task.type`, `customer_id: $.context.customer_id`, `plan: $.context.plan`, `region: $.context.region`

Keep the webhook payload focused. Do not include secrets, credentials, API keys, or unnecessary sensitive data.

Agent Setup

Create an autonomous agent with a narrow name and description, such as External Knowledge Search Agent. Example instructions:

You are a focused research subagent for an external orchestration system.

Answer only the task provided in the current run. Search the available Duckie knowledge before answering. Use tools only when they are directly needed for the task.

Return a concise, structured result to the calling system by using the Send Subagent Result tool. Include the correlation ID from run metadata, the answer, relevant sources, confidence, and any caveats.

Do not send a customer-visible response unless explicitly instructed. If the task cannot be completed safely or confidently, return a low-confidence result with the missing information.

Give this agent access only to the knowledge, runbooks, guidelines, guardrails, and tools required for the subtask. For a search agent, that usually means Duckie knowledge search and the callback custom tool.

Callback Tool

Create a custom tool that posts the result back to your orchestrator API.

POST https://orchestrator.example.com/api/duckie/subagent-results

Example body parameters:

Parameter	Source
`correlation_id`	Fixed value from `{{context.task_id}}` or another run metadata field
`status`	AI-generated enum-style string, such as `complete`, `needs_review`, or `failed`
`answer`	AI-generated result text
`sources`	AI-generated array of source references
`confidence`	AI-generated string, such as `high`, `medium`, or `low`
`notes`	AI-generated caveats or missing information

Use a fixed callback endpoint. Pass task IDs, customer IDs, or routing keys as parameters instead of letting the agent choose a destination URL.

Result Shape

The callback response to your orchestrator can look like this:

{
  "correlation_id": "task_456",
  "status": "complete",
  "answer": "Annual plans are refundable within 30 days if the account has not exceeded the usage threshold.",
  "sources": [
    {
      "title": "Refund Policy",
      "url": "https://example.com/refund-policy"
    }
  ],
  "confidence": "high",
  "notes": "The policy has an enterprise exception; confirm account-specific terms before issuing a refund."
}

Your orchestrator can then decide whether to continue the workflow, ask Duckie another focused task, send a customer response, or route to a human.

Testing

Create the webhook deployment in Testing mode.
Send a representative task payload with a correlation ID.
Open Analyze > Runs and verify the message, metadata, searched knowledge, and tool calls.
Confirm your callback API receives one result for the task.
Test missing context, low-confidence answers, and callback failures before switching the deployment to Live.

Custom Webhooks

Trigger Duckie from your orchestration system.

Custom Tools

Send the subagent result back to your API.

Autonomous Agents

Configure the focused Duckie agent.

Run History

Review the Duckie run, tool calls, and callback result.

Designing Agent Systems

Place this pattern inside a larger agent architecture.

Single Agents vs Sub-Agents

Compare internal delegation with external orchestration.

Overview

Use Case Blueprints

Example Flow

When to Use This Pattern

What to Build

Request Shape

Agent Setup

Callback Tool

Result Shape

Testing

Custom Webhooks

Custom Tools

Autonomous Agents

Run History

Designing Agent Systems

Single Agents vs Sub-Agents

​Example Flow

​When to Use This Pattern

​What to Build

​Request Shape

​Agent Setup

​Callback Tool

​Result Shape

​Testing

​Related Docs

Custom Webhooks

Custom Tools

Autonomous Agents

Run History

Designing Agent Systems

Single Agents vs Sub-Agents

Example Flow

When to Use This Pattern

What to Build

Request Shape

Agent Setup

Callback Tool

Result Shape

Testing

Related Docs