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.
Clinic front deskBooks, moves and cancels appointments
AvailableInstructions
You book clinic appointments. Offer only free slots, and confirm every booking with its reference.
Everything an agent needs, set up in one place.
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.
Each agent gets its own key, so every model call, tool call and run is tied to the agent that made it.
When the steps must be the same every time, lay the process out as a flowchart: a trigger, then agents, tools and decisions.
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.
01Prompt
What the person asked.
02Execution
Each step the agent took, in order, with its timing.
03Tool called
Which tool, and what the agent sent it.
04System accessed
The server or system that tool reached.
05Value returned
What came back from it.
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 ObservabilityTwo gateways around the orchestrator: one for the models agents use, one for the tools they call.
One set of rules for the models your agents use.
One set of rules for the tools your agents call.
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.
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.
Send one message and a conversation ID. We keep the history.
{
"message": {
"id": "msg-2",
"role": "user",
"parts": [ … ]
},
"conversationId": "…"
}Send the whole conversation each time. Nothing is stored.
{
"messages": [
{ "role": "user", … },
{ "role": "assistant", … },
{ "role": "user", … }
]
}Send only template values, with no chat message.
{
"vars": {
"customer": "Acme",
"tone": "formal"
}
}vars (template values) also work with either chat mode.
Attach images and documents to any message, and the agent reads them along with the text.
25 MB
"url": "https://…"data:image/png;base64,…Uploaded for you
Files sent next to the rest of the request.
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.
Every answer shows how much AI usage it took. When something goes wrong, the error says what happened in plain words.
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.
/api/agents/{agentId}/runBest 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"}]}}'/api/agents/{agentId}/runBest 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
}/api/agents/{agentId}/conversations/{conversationId}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"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 agentFor a chat window or assistant tied to a single agent.
cf-api-keyWhole organisationFor your own services and workflows that use several agents. You can revoke it any time.
AuthorizationSigned-in userFor apps where people already sign in to Chocolate Factory.
Organisation keys are generated in organisation settings, and shown exactly once.