Studio

A Studio agent is an agent a person builds in the console with no code: its instructions, how it opens a call, the requests it may make to the business's own API, and what it collects from the caller. Nothing is installed and no process of the org's runs it: the gateway holds it, on an app socket of its own whose frames never leave the process, and answers its calls from the definition with the same wire an SDK speaks (The smallest app that works). For everything else a Studio agent is an agent: its settings (voice, models, language), its knowledge, lexicon, numbers, personas, judges and calls are the same rows and the same screens.

A Studio agent is a hosted app (Hosted apps) of the kind studio: the org's hosted_apps quota counts it, its time is metered as an app's is, and its releases are its definition as JSON. The Apps list shows it beside the apps the runner starts; stop, start, rollback and remove work on it by name. Every endpoint here takes a key that opens app.

The definition#

{
  "instructions": "You answer the phone for Clínica Norte. The caller dials from {{call.from}}.",
  "greeting": {"say": "Clínica Norte, good morning."},
  "tools": [{
    "name": "findPatient",
    "description": "Finds the patient by phone.",
    "method": "GET",
    "url": "https://agenda.example.com/patients/{phone}",
    "headers": [{"name": "Authorization", "value": "Bearer {{secrets.AGENDA_KEY}}"}],
    "params": [{"name": "phone", "type": "string", "description": "the caller's number", "required": true}],
    "announce": "Let me look you up.",
    "timeout_s": 10
  }],
  "collect": {
    "fields": [{"name": "name", "type": "string", "description": "the full name", "required": true}],
    "end_when_done": true,
    "closing": "Thank the caller, say goodbye, and end the call.",
    "send_to": "https://agenda.example.com/calls",
    "headers": []
  }
}

Refused when it is saved, with a sentence, never on a call: two tools of one name, a tool called as one of the platform's own (collect, end_call, current_date, recall, search, say), a URL that is not https://, a {param} in a URL that is none of the tool's parameters, a secret named anywhere but a header's value (the instructions, a greeting, a description, a URL: every string of the definition is read, with one sentence saying which), and a secret the env has none of. A deploy checks production's own secrets: one set in the sandbox alone is said before production answers a call.

The fence. The gateway reaches what a tenant typed, so every request is held to the public internet: https only, the name resolved and every address public (never loopback, private, link-local — the cloud's metadata address — or a name the box answers to, .svc, .internal), no redirect followed, the answer read up to 256 KB, the tool's own timeout (10 s unless it says, 30 s at most). A secret travels in the request's headers alone: never in the prompt, the log, a tool.call or a tool.result. An API that sends it back (one that echoes the headers it got) has its value masked as *** in the answer, by value and wherever it came back, before the model, the log, the tool.result or Try's answer holds it. The name is resolved before the request and again by the HTTP client, so a DNS answer that changes between the two is not ruled out: the webhooks of alerts take the same risk.

How the gateway holds it#

At its start, and whenever an org's Studio agents change (a save, a deploy, a stop, a start, a rollback, a removal, said on the signal's studio channel), every gateway holds each running Studio agent's newest release on its own socket for the org and env: agent.register with sdk: "studio", then agent.configure with the tools, the greeting, the collected fields as state and the hang-up. The registry treats it as any holder — several gateways hold it and the newest takes a call; a gateway that stops drains and its calls go to another's socket. GET /v1/apps lists the socket as the process pinecall-studio. An app of the org's that registers a Studio agent's slug is refused: a slug is one agent.

For each call the socket is sent the call's entries as any app is: at call.started (or call.attached, rebuilding the call from its state) it sends state.set with what is collected, prompt.set for identity, tools and view, and tools.set; at tool.call it sends the request or runs collect, then tool.result; at call.ended it posts the results. The one tool.call it leaves alone is end_call, the hang-up the model uses when end_when_done lets it: the session writes that call and its result itself, so the call has one result. In the sandbox a save reaches the calls already open: the socket sends again the blocks that changed and tools.set, so a call's next turn runs on the new definition (the console's Try it is one). In production a call keeps the definition it opened on while it runs on that gateway, and a deploy answers from the next call; a call handed to another gateway is rebuilt on the newest release.

The endpoints#

From a terminal it is pinecall studio (cli/docs/the-cli.md); from an assistant the MCP's studio tool; in the console, the agent's Studio row and Agents ▸ New agent.