Skip to main content

Multi-Agentic Systems

A multi-agentic system is an AI application where multiple actors collaborate to complete a task. Each actor has a clear responsibility, and the workflow decides which actor should work next.

This is useful when a single general-purpose agent becomes too broad, difficult to control, or hard to explain.

What Multi-Agent Workflows Mean​

A multi-agent workflow usually contains:

  • Router: Decides where a user request should go
  • Specialist workers: Handle specific domains such as billing, technical support, retrieval, or escalation
  • Tools: Perform actions such as search, calculations, ticket creation, or API calls
  • State: Carries context from one step to another
  • Controls: Add conditions, approvals, and fallback behavior

For example, a customer support workflow can work like this:

  1. User asks a question
  2. Router classifies the request as billing, technical, or general
  3. Billing worker checks invoice or refund tools
  4. Technical worker runs diagnostics or creates a ticket
  5. Escalation worker pauses for human approval when needed
  6. Final response is returned and stored in the conversation thread

Why Not Use One Agent for Everything?​

A single agent can work well for simple use cases. But as the use case grows, one large agent often becomes harder to manage.

Multi-agent workflows help because they provide:

  • Clear ownership of each task
  • More predictable routing and tool use
  • Better control over sensitive actions
  • Easier debugging and evaluation
  • A cleaner path to production readiness

When to Use a Multi-Agentic System​

Use a multi-agentic system when your use case has:

  • Multiple business domains
  • Different tools for different tasks
  • Approval requirements for critical actions
  • Long-running workflows
  • A need to inspect or resume workflow state

For simple Q&A or a single tool-based assistant, a single-agent setup may be enough.

How Agents SDK Solves This with LangGraph​

The CAIP Agents SDK supports multi-agentic systems through LangGraph. You define the workflow logic, and the SDK handles the common platform work around configuration, LLM setup, threads, tools, and message persistence.

With framework="langgraph", the SDK provides:

  • A unified CAIPAgentsClient
  • Agent configuration loaded from CAIP Agents API
  • CAIP LLM API based model setup
  • Conversation thread and message persistence
  • Tool registration through the same SDK patterns
  • Checkpoint controls (create_checkpoint_config, resume, get_state, get_state_history, update_state)
  • Structured event streaming through astream_events()

This means your application can focus on graph design instead of rebuilding the operational layer.

Execution APIs in LangGraph Mode​

Use one of these paths depending on your use case:

  • Assistant-style: run() and stream() for normalized output and conversation persistence
  • LangGraph-native: ainvoke(), astream(), and astream_events() when you want direct graph payload/event control

run() returns LangGraphRunResult, including:

  • output: final assistant text
  • raw: raw graph output payload
  • is_interrupted() and interrupts() helpers for HITL flows

Checkpoint and Thread Requirements​

For checkpoint-based execution, always set thread_id and pass checkpoint config consistently:

thread = await client.create_thread(agent_id="your-agent-id", thread_data={"title": "Support", "status": "open"})
agent.thread_id = thread.threadId

checkpoint_config = agent.create_checkpoint_config(thread.threadId, checkpoint_ns="support")

result = await agent.run("Escalate this to a manager", config=checkpoint_config)
if result.is_interrupted():
	result = await agent.resume("approve", config=checkpoint_config)

This keeps workflow state isolated per thread/namespace and enables consistent pause/resume/state inspection behavior.

What You Define​

In a LangGraph workflow, you define:

  • Nodes, such as router, billing worker, technical worker, and escalation worker
  • Edges, which decide how execution moves between nodes
  • Tools, attached to the workers that need them
  • State, usually based on LangGraph message state
  • Optional interrupt points for human approval

Basic SDK Pattern​

from caip_agents_sdk import CAIPAgentsClient

client = CAIPAgentsClient()

agent = client.create_agent(
	framework="langgraph",
	agent_id="your-agent-id",
)

This creates a LangGraph-backed agent client using the same SDK entry point used by other supported frameworks.

Next, read LangGraph - Orchestration Framework to understand the framework concepts behind this orchestration model.