In From Cocoa to Chocolate, agents are built and run in the Agent Orchestrator. The Run API is how they leave the factory: the way any app the business owns puts an agent in front of the people who use it. This piece walks through it in full.
Out of the factory, into every app
Agents are only useful where people actually work, and much of that work happens inside the business’s own software. An agent that lives only in a separate window is an agent people have to remember to visit.
The Run API lets any app run any agent from one address, with the agent’s ID and a key. Every run it starts is traced like any other, so an agent inside an app is on the same record as an agent anywhere else. Leaving the factory does not mean leaving its rules.
The app does not rebuild the agent. The instructions, knowledge, tools, memory and run limits are set once in the Agent Orchestrator, and the app calls the agent that already has them. The same agent can answer in Microsoft Teams, on WhatsApp and inside the business’s own software, under the same rules in each.
One call, two ways to get the answer
The same call can return the answer in whichever form suits the app.
Live, word by word
As the agent writes it
- Suits chat windows and in-app assistants
- Nobody sits waiting for the full answer
One complete answer
Returned all at once
- Suits forms, generated content and saved prompts
- Suits background jobs
Saved conversations can be fetched again later, to show a chat or check what was said.
Keep the chat history, or don’t
The business chooses where conversation history lives. That is a decision about data as much as about convenience, and it belongs to the business, not to the platform.
Persisted
The app sends one message and a conversation ID, and Chocolate Factory keeps the history.
Stateless
The app sends the whole conversation each time, and nothing is stored.
Prompt-only
The app skips the chat entirely and runs a saved prompt by filling in its template values.
Each mode suits a different need. Persisted mode lets an app hand the conversation to Chocolate Factory and fetch it again later. Stateless mode suits an app that must hold the conversation itself and leave nothing stored. Prompt-only mode suits work that is not a conversation at all, such as filling a form or generating content from a saved prompt. Template values work in either chat mode too, so a saved prompt can sit inside a conversation as easily as it runs on its own.
Context passed safely to connected apps
An app can hand the agent extra details, such as which customer is asking or which region they are in, and the agent passes them on to the tools it uses. Anything sensitive, such as authorisation headers, is stripped out first.
The agent gets what it needs to do the job well. What it should never carry onward stays behind. The tools it passes those details to are still governed as before: the agent can only reach the systems, and take the actions, it has been allowed.
Clear usage and plain errors
Every answer reports how much AI usage it took, in input and output tokens. Usage is never a surprise discovered later; it arrives with the answer.
When something goes wrong, the error comes back plainly, with a clear status. The app can tell a request it got wrong from a key that is not allowed, and an agent that does not exist from one that has been switched off, and say so to the person using it.
What an error tells you
- The request was bad
- The call was unauthorised
- The call was forbidden
- The agent cannot be found
- The agent is inactive
Three ways to authenticate
Every request carries a credential, and the credential decides how far it can reach. Reach is matched to the job: a narrow key for a narrow task, a broad one only where it is needed.
| Credential | Reaches | Suits |
|---|---|---|
| Agent key | One agent | A chat window or assistant tied to that agent |
| Organisation key | Every agent the organisation owns | The business’s own services and workflows |
| Signed-in user | That user’s own authorisation | Apps where people already sign in to Chocolate Factory |
An organisation key is generated in organisation settings, shown exactly once, and can be revoked at any time. Each key shows when it was last used, so a key nobody uses any more is easy to spot and withdraw.
The choice of credential is a choice about risk. A chat window tied to one agent never needs a key that reaches every agent the organisation owns, so it is given one that cannot. A service that coordinates several agents gets the wider key, generated once, held by the business, and revocable the moment it is no longer needed.
Every request carries a credential, every credential has a reach, and every key can be taken back.
What it changes
Developers stop rebuilding plumbing. The Run API puts any agent inside their own apps, live or as one complete answer, with files, context and the business’s choice of where history lives. Agents meet people where they already work, and every run they start stays on the record.
The Run API is part of the Agent Orchestrator; its details are on the Agent Orchestrator page.
The short version
- One address, an agent’s ID and a key; every run it starts is traced.
- Answers arrive live, word by word, or all at once.
- The business chooses where conversation history lives, or skips the chat for a saved prompt.
- Agent, organisation and signed-in user credentials each reach only as far as they should.



