AGNT Orchestration

Orchestration is not a separate API you call. It's the built-in intelligence layer that makes Chats and Tasks work together seamlessly. When a user sends a chat message, orchestration is what parses the intent, creates tasks, selects the right skills, routes work to the right assistant, and coordinates execution — all automatically.

You don't wire any of this up. You use Chats and Tasks, and orchestration happens.

Why AGNT Orchestration

Most teams building AI agents end up writing the same invisible infrastructure:

• Intent parsing — figuring out what the user actually wants from a raw message
• Task creation — turning intent into structured work items
• Skill matching — deciding which capabilities to invoke
• Routing — sending work to the right assistant based on type, skills, and context
• Decomposition — breaking complex requests into smaller, manageable steps
• Execution coordination — running tasks synchronously or queuing them, handling failures, tracking status

This is plumbing. It's necessary, it's complex, and it's the same for every agent system. Teams spend weeks building it, and the result is usually a fragile, inconsistent routing layer that breaks when requirements change.

AGNT Orchestration handles all of it. The moment you send a message through Chats or create a task through Tasks, orchestration takes over. You focus on defining your assistants, their skills, and your task types. The platform handles how work flows between them.

How It Works

The Invisible Flow

Here's what happens when a user sends a chat message:

User sends message via Chats API
        ↓
  Intent Parsing
  "What does this person want?"
        ↓
  Task Creation
  Raw intent → structured task with type, priority, context
        ↓
  Skill Matching
  "What capabilities does this task need?"
  Task type + context → matched skills
        ↓
  Assistant Routing
  "Which assistant has the right skills?"
  Required skills + availability → selected assistant
        ↓
  Execution
  Sync (immediate) or queued (async via SQS)
        ↓
  Response Routing
  Result flows back through the chat as a message

Every step is automatic. The developer's job is to define the building blocks — assistants with their skills, task types, and any routing preferences. Orchestration connects them.

What You Define

What You Don't Build

• No routing logic. You don't write if task.type === 'research' then use researchAgent. Orchestration evaluates task type, required skills, and assigned assistant to route automatically.
• No skill selection code. You don't manually wire which skills activate for which requests. Skills are matched based on the task's type and context.
• No queue management. You don't manage SQS queues, retry logic, or concurrency. Orchestration handles sync vs. async execution transparently.
• No status state machine. You don't write status transition logic. Tasks move through pending → in_progress → completed/failed/on_hold/needs_clarification automatically based on execution results.
• No decomposition logic. For complex work, orchestration breaks tasks into subtasks, each routed and executed independently. The parent task tracks aggregate status.

Core Concepts

Chat-to-Task Bridge

This is the most visible thing orchestration does. A raw chat message — unstructured natural language — gets parsed into a structured task. The task inherits context from the chat (conversation history, user identity, assistant assignment) and enters the execution pipeline.

The developer sends a chat message via POST /chats/:chatId/messages. Orchestration creates a task, processes it, and routes the result back as a chat response. The developer never directly creates a task from a chat — orchestration does it.

Skill Selection

Every assistant has a set of skills. Every task type maps to required capabilities. When a task is created, orchestration matches the task's requirements against available skills and activates the right ones.

This means you can add a new skill to an assistant and tasks that need it will automatically start using it — no routing code to update, no deployment needed.

Subtask Decomposition

When a request is too complex for a single execution pass, orchestration breaks it into subtasks. Each subtask:

• Has its own type, priority, and status
• Routes to the right assistant independently
• Executes on its own timeline
• Reports status back to the parent task

The parent task tracks aggregate progress. If three out of four subtasks complete and one fails, the parent reflects that state. You can build UIs that show a progress tree: "Researching competitors (done) → Analyzing pricing (in progress) → Writing summary (pending)."

Execution Modes

Orchestration runs tasks two ways:

• Synchronous — process the task immediately and return the result. Used when you need an instant response (e.g., chat reply).
• Queued — push the task to the execution queue for async processing. Used for background work, batch processing, or when the task might take a while.

Both modes produce the same result. The difference is whether your code waits for it or polls for it. Orchestration chooses the right mode based on context, or you can specify it explicitly through the Tasks API.

Status Lifecycle

Every task moves through a defined set of statuses:

pending → in_progress → completed
                      → failed
                      → on_hold
                      → needs_clarification

Status transitions are automatic. When needs_clarification is hit, orchestration routes the clarification request back through the chat so the user can respond — and when they do, the task resumes.

Activity Log

Every orchestration decision is recorded:

• Which assistant was selected and why
• Status transitions (with timestamps)
• Execution attempts (start, completion, failure)
• Subtask creation and completion
• Feedback events

The activity log is append-only. You can always reconstruct the full history of how orchestration handled a piece of work. Access it through the Tasks API.

Quick Start

Send a chat message and watch orchestration handle the rest:

# 1. Send a message through Chats
curl -X POST "https://api.agnt.ai/chats/$CHAT_ID/messages" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Research competitor pricing for Q2 launch planning"
  }'

Behind the scenes, orchestration:

1. Parsed the intent ("research request about competitor pricing")
2. Created a task with type research and high priority
3. Matched the task to the assistant assigned to this chat
4. Selected relevant skills (web research, document synthesis)
5. Executed the task
6. Routed the result back as a chat response

You didn't create a task. You didn't select skills. You didn't route anything. You sent a message.

If you want more control

Use the Tasks API directly to create tasks with explicit types, priorities, and assignments. Orchestration still handles skill selection, execution, and status management — but you control the inputs:

curl -X POST "https://api.agnt.ai/tasks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Research competitor pricing",
    "description": "Analyze pricing pages for top 5 competitors and summarize findings.",
    "assistantId": "asst_research01",
    "type": "research",
    "priority": "high"
  }'

All task endpoints, parameters, and response shapes are documented in Tasks.

For Coding Agents

If you're a coding agent integrating with AGNT, orchestration is the layer you benefit from without building. Here's what matters:

1. Send chat messages, get structured work done. You don't need to build task routing. Send a message through Chats, and orchestration creates tasks, selects skills, executes, and responds. Your integration can be as simple as a chat conversation.

2. Use Tasks for explicit control. When you need specific task types, priorities, or assignments, use the Tasks API directly. Orchestration still handles execution and skill selection — you just provide more structured inputs.

3. Handle needs_clarification. When orchestration hits a task it can't complete without more context, it routes a clarification request back through the chat. Your agent needs to detect this and provide additional context — either programmatically or by routing to a human.

4. Let subtasks happen. Complex work gets decomposed automatically. Don't try to micromanage multi-step workflows by creating individual tasks — let orchestration break down the work. Monitor progress through the parent task's status and activity log via the Tasks API.

5. Trust the skill matching. Add skills to assistants, define task types, and let orchestration connect them. If you find yourself writing if/else routing logic, you're doing orchestration's job — configure it instead.

For Product Teams

Your users don't need to understand any of this. Orchestration is invisible to end users. They send messages in a chat and get results. The complexity of routing, skill selection, and execution coordination happens behind the scenes.

Think of it as the brain. If Chats are the conversation and Tasks are the work items, Orchestration is what connects them. It's the reason a simple chat message can trigger complex, multi-step agent work without anyone building the wiring.

Subtasks make complex work transparent. When you show users a task breakdown — "Researching competitors (done) → Analyzing pricing (in progress) → Writing summary (pending)" — that breakdown comes from orchestration's automatic decomposition. You get structured progress for free.

No routing configuration needed. You define assistants and their skills. You define task types. Orchestration handles the rest. When product requirements change — new task types, new skills, different routing priorities — you update the configuration, not the code.

Quality signals flow through. The feedback mechanism on tasks (like/dislike) feeds back through orchestration. Over time, this gives you quality data across every type of work your agents handle — accessible through the Tasks API.