Set connected app scope
Give this agent a connected app, and choose which of its tools it can call. A workspace connects an app once (on the Connected apps page, agent_id NULL) and that is the ACCOUNT, not a grant: it arms no agent by itself. This op writes THIS AGENT'S opt-in row against that account, and that row is the only thing the runtime reads, an agent without one loads none of the app's tools. **The app must already be connected for the workspace**, this op can't connect a new app, only opt an agent into an existing one (a not-connected toolkit returns a 409). Use `enabled: false` to stop this agent loading the app while the workspace account stays connected for the others. Use `allowedTools` to trim the tools the agent loads: `null` = the recommended subset (the fast default, DON'T load a whole 800-tool toolkit), a list = exactly those slugs, `[]` = none. Omit a field to leave it unchanged.
Authorization
bearerAuth A personal access token from Settings > API tokens.
In: header
Header Parameters
A key you choose, such as a UUID, that makes this POST safe to retry. Within 24 hours the same key and request answers with the first successful answer and runs nothing, the same key with a different request answers 422 idempotency_key_reused, and a key whose request is still running answers 409 idempotency_key_in_use. A failed request keeps nothing, so the same key runs it again.
1 <= length <= 255Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
curl -X POST "https://example.com/operations/set_agent_connection" \ -H "Content-Type: application/json" \ -d '{ "toolkit": "string", "agent": "string" }'{}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}Set channels POST
Declare which channels the agent serves: 'voice' (phone numbers and the website call pill, billed per minute) and/or 'text' (the website chat widget and share link, billed per reply). At least one. Turning 'text' off switches the chat widget off and turning it on switches it on; turning 'voice' off switches the call pill off. Voice settings stay stored on a chat-only agent, hidden in the editor. A chat agent must run on a model priced per reply (validate_agent reports it).
Set agent response guardrails POST
Set the draft's agent response guardrails: yes or no questions a classifier answers about each reply the agent writes, on calls and in chat. Use regenerateWhen for business rules, such as never quoting a price. On a call each reply plays at once and is checked as it plays; in chat a reply is checked before it is sent. Two lists. blockUnless: the reply is blocked unless one of these is yes, so the agent stops talking, such as staying quiet while a signed-off worker reports a job step by step; the caller can hear a blocked reply's first words before it stops, and a block ends the caller's turn, so their next words are judged on their own. regenerateWhen: yes means the reply broke the guardrail, so the reply is cut off, the agent says fillerLine on a call (chat shows nothing), and the model answers again with the broken question in its context; a second break in the same caller turn speaks fallbackLine instead. Each question has an id unique across both lists, the question, optional yes and no criteria, a threshold and readsJobContext; each list replaces the saved one. A blockUnless question also takes checks. agentResponse, the default, asks about the reply while it plays. userTurn asks about the caller's words alone, beside the model as it starts writing, and holds the reply's first words until it answers, which is usually before the first word exists; a yes lets the reply out, and when every userTurn answer is no the reply is dropped and never plays a word, so a one-word acknowledgement can't slip out before its check, unless the list also has agentResponse questions, in which case the reply plays and is cut off unless one of them says yes. blockUnless never makes the agent answer again. The classifier reads the job context, what the agent last said, what the caller has said since and the reply. jobContext is static text with {{variables}} filled; contextTools are tools whose latest result before the caller's last words becomes job context, each with an optional dot path field, such as start_job with field procedure; clearTools end the job; classifierTimeoutSecs; failMode. With context tools set, replies go out unchecked until one of them returns. Fields you leave out keep their saved values. Try a transcript with test_agent_response_guardrails, then publish. They run on calls, in chat and in text tests. An agent on speech to speech runs with separate listening, reply and voice models while these are on.