Skip to main content

Agent Orchestrator

Build, orchestrate and govern your AI agents.

Clinic front deskBooks, moves and cancels appointments

Available

Instructions

You book clinic appointments. Offer only free slots, and confirm every booking with its reference.

Model
Claude Sonnet
Knowledge
Clinic handbook
Tools
Document Generator
MCP
Clinic calendar · read, book
Memory
On
Schedule
Daily reminders, 08:00
Channels
WhatsApp · Teams
Works with
Billing agent

Create and manage agents.

Everything an agent needs, set up in one place.

Instructions and a model

Available

Write the system prompt that sets the agent's role and rules. Then choose the model behind it, from the models your project has turned on.

  • System prompt
  • A model per agent
  • Limits on how far it runs

An identity for every agentAvailable

Each agent gets its own key, so every model call, tool call and run is tied to the agent that made it.

Business processes in the Business Process Studio

Available

When the steps must be the same every time, lay the process out as a flowchart: a trigger, then agents, tools and decisions.

How workflows are built

Every step of every run, on the record

Available

Open any run and read it in order: what was asked, how the agent worked through it, which tool it called, which system that tool reached, what came back, and the final answer.

  1. 01Prompt

    What the person asked.

  2. 02Execution

    Each step the agent took, in order, with its timing.

  3. 03Tool called

    Which tool, and what the agent sent it.

  4. 04System accessed

    The server or system that tool reached.

  5. 05Value returned

    What came back from it.

  6. 06Final response

    The answer the person saw.

Why it matters. When an answer is wrong, you see the step where it went wrong. So you tune agents with evidence instead of running blind.

Logs, volume and root cause on Observability

The harness.

Two gateways around the orchestrator: one for the models agents use, one for the tools they call.

Agent OrchestratorAvailable

AI Gateway

Available

One set of rules for the models your agents use.

  • List, register and manage model providersAvailable
  • Fallback to another model or hostAvailable
  • Virtual keys for teams and membersAvailable
  • Budgets per team, member or keyAvailable
  • Keys that expireAvailable
  • Spend caps with a circuit breakerAvailable
About the AI Gateway

MCP Gateway

Available

One set of rules for the tools your agents call.

  • Tool registryAvailable
  • AuthenticationAvailable
  • Tool filteringAvailable
  • Access control, such as allow read and deny writeAvailable
  • Metering and budgetsAvailable
  • Audit logAvailable
About the MCP Gateway

Use case: an appointment-booking agent.

A patient asks to book a check-up. The agent checks the clinic's calendar, offers the free slots, books the one the patient picks and confirms it. The trace records each step.

AvailableBuilt from the parts above: instructions, a calendar connected through MCP, WhatsApp and the trace.

Run agents from your own apps.

Available

Keep the chat history, or don't

We can remember each conversation for you, your app can keep it instead, or you can skip the chat and simply run a saved prompt.

Persisted

Send one message and a conversation ID. We keep the history.

{
  "message": {
    "id": "msg-2",
    "role": "user",
    "parts": [ … ]
  },
  "conversationId": "…"
}

Stateless

Send the whole conversation each time. Nothing is stored.

{
  "messages": [
    { "role": "user", … },
    { "role": "assistant", … },
    { "role": "user", … }
  ]
}

Prompt-only

Send only template values, with no chat message.

{
  "vars": {
    "customer": "Acme",
    "tone": "formal"
  }
}

vars (template values) also work with either chat mode.

Send files with a message

Attach images and documents to any message, and the agent reads them along with the text.

Images

  • JPEG
  • PNG
  • GIF
  • WebP

Documents and spreadsheets

  • PDF
  • TXT
  • MD
  • DOCX
  • XLSX
  • XLS

Per file

25 MB

HTTPS link

"url": "https://…"

Base64 data URL

data:image/png;base64,…

Uploaded for you

Multipart form data

Files sent next to the rest of the request.

Pass extra details to connected apps

Your app can hand the agent extra context, like which customer is asking, and the agent passes it on to the tools it uses. Anything sensitive is stripped out first.

Clear usage and plain errors

Every answer shows how much AI usage it took. When something goes wrong, the error says what happened in plain words.

One call, two ways to get the answer

Your app calls one address with the agent's ID and a key, then picks how the answer arrives: word by word, or all at once.

POST/api/agents/{agentId}/run

Live answers

Best for chat windows and in-app assistants. Words appear as the agent writes them, so nobody sits waiting.

Request

curl -X POST "https://yourdomain.com/api/agents/YOUR_AGENT_ID/run" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -H "cf-api-key: cf_xxxxxxxx" \
  -d '{"message":{"id":"msg-1","role":"user",
       "parts":[{"type":"text","text":"Hello"}]}}'
POST/api/agents/{agentId}/run

One complete answer

Best for forms, generated content, saved prompts and background jobs. Ask once, get the full answer back.

Response

{
  "text": "Generated output from the agent",
  "usage": {
    "inputTokens": 123,
    "outputTokens": 456,
    "totalTokens": 579
  },
  "finishReason": "stop",
  "conversationId": null
}
GET/api/agents/{agentId}/conversations/{conversationId}

Conversation history

Bring back a saved conversation to show the chat again or check what was said.

Request

curl "https://yourdomain.com/api/agents/YOUR_AGENT_ID/conversations/CONVERSATION_ID" \
  -H "cf-api-key: cf_xxxxxxxx"

Three ways to authenticate

Every request carries a credential. Which one you choose decides how much it can reach. Treat all three as secrets — an organisation key opens every agent you own.

x-agent-keyOne agent

For a chat window or assistant tied to a single agent.

cf-api-keyWhole organisation

For your own services and workflows that use several agents. You can revoke it any time.

AuthorizationSigned-in user

For apps where people already sign in to Chocolate Factory.

Organisation keys are generated in organisation settings, and shown exactly once.