Subagents

What is a subagent?

A subagent is a scoped AI agent you deploy with a single prompt. Each subagent is an expert in one domain — CRM, billing, media processing, data analysis — with access to every tool it needs within that domain.

You deploy it once. Then your agent routes tasks to it.

curl -X POST https://api.ploton.ai/v1/subagents \
  -H "Authorization: Bearer $PLOTON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "crm-agent",
    "prompt": "Handle CRM tasks. Connect Salesforce, HubSpot, and Pipedrive. Manage OAuth, pull contacts, sync deals, export data."
  }'

{
  "id": "crm-agent",
  "tools_available": 14,
  "status": "deployed"
}

That’s the magic moment. One prompt, one subagent, 14 tools ready to go.

How subagents differ from tools

Tools are individual capabilities — a CRM API, a database connector, a shell command. A subagent is an expert that orchestrates multiple tools within a domain.

Tools are building blocks. Subagents are the builders.

Tool:       "I can call the Salesforce API"
Subagent:   "I can connect Salesforce, HubSpot, and Pipedrive.
             I handle OAuth, pull contacts, sync deals, export
             data, and I know the rate limits for each one."

When you deploy a crm-agent, it automatically gets access to every CRM-related tool — Salesforce, HubSpot, Pipedrive, and more. You don’t wire them up individually.

Scoped boundaries

Boundaries are enforced server-side by Ploton. A crm-agent cannot access payment tools. A billing-agent cannot read CRM data. This happens automatically based on the subagent’s domain.

You don’t write boundary rules in your system prompt. You don’t build permission systems. The subagent itself IS the boundary.

System prompt integration

Your agent’s system prompt lists the subagents it can delegate to:

You have access to these Ploton subagents:
- crm-agent: CRM and sales data
- billing-agent: Payments and invoices
- media-agent: Image and video processing

When a request needs capabilities you don't have,
delegate to the relevant subagent.
If no subagent fits, decline the request.

That’s it. Your agent decides which subagent handles the request based on the user’s ask.

Routing tasks to subagents

When your agent needs to delegate, it sends a task with the sub_agent parameter:

curl -X POST https://api.ploton.ai/v1/tasks \
  -H "Authorization: Bearer $PLOTON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Connect Salesforce and pull pipeline data",
    "sub_agent": "crm-agent",
    "user_id": "user_123"
  }'

The subagent handles everything from there — auth, tool selection, workflow generation, error recovery. Your agent gets the result back via webhook.

The full loop

sequenceDiagram
    participant User
    participant Agent
    participant Ploton
    participant Subagent
    participant Service

    User->>Agent: "Connect my Salesforce and pull pipeline data"
    Agent->>Agent: Check system prompt for subagents
    Agent->>Ploton: POST /v1/tasks + sub_agent: crm-agent
    Ploton->>Subagent: Route to crm-agent
    Subagent->>Service: Auth, fetch, execute
    Service-->>Subagent: Data
    Subagent-->>Ploton: Result
    Ploton-->>Agent: Webhook (task.complete)
    Agent->>User: "Done! Your pipeline data is in the Google Sheet."

Pre-built vs. custom subagents

Ploton ships pre-built subagents for common domains. You can also deploy your own with a custom prompt tailored to your specific services.

Pre-built subagents come with tool knowledge and execution memory already built in. Custom subagents start fresh and build execution memory as tasks run through them.

See the Deploying Subagents guide for the full setup walkthrough.

Next steps

• Tasks — How tasks are created and routed to subagents
• Tools — The capabilities subagents use under the hood
• Deploying Subagents — Deploy, configure, and manage subagents