Skip to main content
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 fixed callback API with 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.
  • 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

ComponentPurpose
Customer-owned orchestration agentOwns the parent workflow and decides when Duckie should be called.
Custom webhook deploymentReceives the task payload and starts the Duckie agent.
Focused Duckie agentPerforms one narrow task, such as search or classification.
Custom callback toolSends the final result back to your orchestrator API.
Correlation IDConnects 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 fieldExample mapping
Event ID$.event.id
Ticket ID$.task.id
Ticket TitleDuckie subagent task {{task.id}}
Message Body{{task.question}}
Run Metadatatask_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:
ParameterSource
correlation_idFixed value from {{context.task_id}} or another run metadata field
statusAI-generated enum-style string, such as complete, needs_review, or failed
answerAI-generated result text
sourcesAI-generated array of source references
confidenceAI-generated string, such as high, medium, or low
notesAI-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

  1. Create the webhook deployment in Testing mode.
  2. Send a representative task payload with a correlation ID.
  3. Open Analyze > Runs and verify the message, metadata, searched knowledge, and tool calls.
  4. Confirm your callback API receives one result for the task.
  5. 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.