Agents / TypeScript SDK
Trigger agent role
Create a work order for one Agent Teams role. Hosted mode starts Pipeline inference asynchronously. External mode leaves the work order ready for claim-agent-work-order so a coding agent can use its own subscription. Returns { runId, workOrderId }. For role sdr with external_agent, deterministically detect quiet threads in the configured Inbox owner scope and return pending chat turns for claim-agent-chat-turn and complete-agent-chat-turn. Completion saves pending native drafts and CRM review tasks, never sends. The strategist has dedicated tools and is rejected here.
pipeline.triggerAgentRoleBackend AI, consent requiredParameters
workspaceIdOptional · string- Optional with an API key (inferred from the key).
roleRequired · string- The agent role to run, e.g. scout, researcher, icp, writer, campaign_builder, closer, coach, sdr (external draft-only). Not strategist.
taskOptional · string- Optional free-text task/guidance for the run.
externalSdrModeOptional · string- SDR external mode only. detect (default) checks quiet threads now. queued only returns existing Pipeline-scheduled drafting jobs, without detecting new work.detect · queued
briefIdOptional · string- Campaign brief ID. Required for Scout, campaign_builder, and Writer in external_agent mode so outputs are bound to the current brief version.
tableIdOptional · string- Exact table ID. Required for external Researcher, ICP, and Writer work.
rowIdsOptional · array- Exact row IDs assigned to the external agent. Required for external Researcher, ICP, and Writer work.
outputColumnIdsOptional · array- Exact output-role column IDs the agent must populate and complete. Required for external Researcher and ICP work.
executionModeOptional · string- Coding-agent tools default to external_agent. Set pipeline_hosted and allowHostedAi=true to explicitly use workspace BYOK inference.pipeline_hosted · external_agent
allowHostedAiOptional · boolean- Must be true when this operation uses Pipeline hosted inference.
await pipeline.triggerAgentRole({
"role": "example",
"allowHostedAi": true
})Full input schema
{
"type": "object",
"properties": {
"workspaceId": {
"type": "string",
"description": "Optional with an API key (inferred from the key)."
},
"role": {
"type": "string",
"description": "The agent role to run, e.g. scout, researcher, icp, writer, campaign_builder, closer, coach, sdr (external draft-only). Not strategist."
},
"task": {
"type": "string",
"description": "Optional free-text task/guidance for the run."
},
"externalSdrMode": {
"type": "string",
"enum": [
"detect",
"queued"
],
"description": "SDR external mode only. detect (default) checks quiet threads now. queued only returns existing Pipeline-scheduled drafting jobs, without detecting new work."
},
"briefId": {
"type": "string",
"description": "Campaign brief ID. Required for Scout, campaign_builder, and Writer in external_agent mode so outputs are bound to the current brief version."
},
"tableId": {
"type": "string",
"description": "Exact table ID. Required for external Researcher, ICP, and Writer work."
},
"rowIds": {
"type": "array",
"items": {
"type": "string"
},
"description": "Exact row IDs assigned to the external agent. Required for external Researcher, ICP, and Writer work."
},
"outputColumnIds": {
"type": "array",
"items": {
"type": "string"
},
"description": "Exact output-role column IDs the agent must populate and complete. Required for external Researcher and ICP work."
},
"executionMode": {
"type": "string",
"enum": [
"pipeline_hosted",
"external_agent"
],
"description": "Coding-agent tools default to external_agent. Set pipeline_hosted and allowHostedAi=true to explicitly use workspace BYOK inference."
},
"allowHostedAi": {
"type": "boolean",
"description": "Must be true when this operation uses Pipeline hosted inference."
}
},
"required": [
"role"
]
}