Preset Agents

A preset agent is a saved configuration that callers invoke like a model. It fixes the model the agent runs on, a system prompt, a set of tool servers, and optionally locked sampling parameters. A caller sends the agent's name in the model field of POST /v1/responses and gets the configured behavior. The caller cannot see or override the prompt, and does not need direct access to the agent's model or tools — access to the agent is enough.

Model Gateway describes the invocation contract, and Tools with the Responses API describes how the agent's tools reach the model. This page covers creating and managing agents.

Ownership

Every agent has exactly one owner: a tenant, or the platform.

• A tenant-owned agent is created by a tenant admin and belongs to that tenant.
• A platform-owned agent is created by a platform admin and belongs to no tenant.

The agent's name is what callers put in the model field. For a tenant-owned agent, the platform adds the tenant in front of the name you type. A tenant named Acme that creates ticket-assistant gets the ID acme-ticket-assistant, and that full ID is what callers send. A platform-owned agent keeps the name exactly as typed.

Use lowercase letters, numbers, - and ., and start and end with a letter or a number. The full ID can be at most 253 characters, the tenant part included. The create form shows the full ID under the Name field while you type. Agent names share one namespace with model names, so creation is refused when the name is already taken.

Sharing

An agent can be shared with selected tenants. Only a platform-owned agent can also be shared with everyone; saving that setting on a tenant-owned agent is refused with share_to_all is only valid for platform-owned preset agents.

You can only configure what you can use

An agent may only point at resources its author can use. When you create an agent, or change its model or tools, the platform checks your own access to the model and to every tool server. If any check fails, the save is refused with you cannot invoke every configured resource.

The model may be an alias (see Model Gateway). The agent then follows the alias: when an administrator points the alias at another model, the agent runs on the new model without an edit. The new model is used from the next call. For a short time after the repoint, the platform is still moving the agent's access to the new model. A call in that window can fail with the not-ready error described under Availability. Wait a moment and call again.

A tool server is a whole server, not a single tool: a RAG deployment or an external MCP server. The agent's callers can use all tools that its servers publish.

Editing

An edit sends only the fields to change:

• An absent field keeps the stored value.
• A present field replaces the stored value completely.
• A field sent present but empty clears the stored value. This is how you clear the instructions, the display name, or the last tool server.

The model is required and cannot be cleared. The name and the owner cannot change after creation.

Locked parameters

An agent can lock three sampling parameters. A caller cannot override them.

Parameter	Value
Temperature	Between 0 and 2
Top P	Between 0 and 1
Maximum output tokens	A whole number, 1 or more

Every parameter is optional. Leave a field blank and the model's own default applies. In the portal the three fields sit under Advanced settings on the create and edit forms. Clear all three and the agent keeps no locked parameters.

Availability

Every agent reports one availability state:

State	Meaning
Ready	The configuration is fully applied. The agent can be invoked.
Reconciling	The platform is applying the latest change. This state is normally brief.
Unavailable	A configured resource does not resolve — for example, the agent's model or a tool server was deleted.

Invoking an Unavailable agent fails with a not-ready error. So does invoking a new agent whose first setup has not finished. A Reconciling agent that was Ready before the change keeps serving. A call in that window can briefly fail with the same not-ready error while new permissions finish applying. An Unavailable agent stays listed, so its owner can fix the configuration.

Conversations

An agent call is a single question and answer, unless you ask the platform to keep the conversation. Two fields on POST /v1/responses control this:

• Send "store": true to start a conversation. The answer carries the new conversation's id in conversation.id.
• Send that id as conversation_id on your next call to continue the conversation. The agent sees the earlier messages.
• Send neither field, or send "store": false, and the call stays a single turn. Nothing is kept.

On a call that carries a conversation_id you may leave input out. The agent then answers from the conversation so far. On a call that starts a new conversation, input is required.

Two requests are refused with 400:

• conversation_id together with "store": false, because the two ask for opposite things.
• An empty input on a call that does not continue a conversation.

You may only use a conversation you own, in your own tenant. Any other conversation is refused with 403.

The conversation keeps your messages and the agent's answers. The agent's system prompt is never kept and never returned.

Finding agents

The agent list answers one of two questions:

• Agents I can use — every agent you may invoke, through ownership or sharing. This is the default view.
• Agents I can manage — every agent you may administer. This includes an agent whose admin granted you admin access on that one agent, so you can find it even when you are not a tenant admin.

In the portal

The portal shows a Preset Agents entry in the navigation when you can manage at least one agent. A tenant admin always sees it. Another member sees it when an agent's admin granted them admin access on an agent.

The list shows the agents you can manage, with the columns Display name, Agent id, Base model, Status, and Access. Every row also has a delete button. Select an agent's display name to open its page.

Add agent opens the create form. Only a tenant admin gets the button. The form offers the models and tool servers you can use. The save is refused when the agent would point at a resource you cannot use, as described under You can only configure what you can use.

The form has no owner choice. A tenant's page creates a tenant-owned agent. A platform admin creates a platform-owned agent from the same page under Manage platform.

An agent's page has an edit button, a Delete preset agent button, the sharing controls, and the per-agent grants. Delete asks for confirmation first. After a delete, calls that send the agent's ID stop working.

The sharing controls sit under Access. Choosing tenants there needs platform tenant-management access. Without it, saving keeps the shared tenants unchanged.

Per-agent permissions

An agent's admin can grant access to that one agent: permission to use it, or permission to manage it. The grant target can be a single user or a whole group. This delegates one agent without sharing anything else.

In the portal, open the agent and find Administrators. The Add administrator button grants manage permission to selected users and groups. It is the only grant kind the portal adds. The table lists every grant with its name, type, and access. A manage grant shows Administrator. A use-only grant shows Direct invoker. Every row has a remove button.

Using an agent in chat

An agent you may use also appears in the Chat picker, shown as Preset agent: <name>. Select it there and write a message — no code and no API key needed. The agent's tools and instructions apply, exactly as they do for a call to POST /v1/responses.

API keys and OAuth tools

• An API key can carry an invoke grant on an agent, so a service can call the agent without a user session. You can grant any agent you can use yourself, including one shared with you from the platform or another tenant. See API Keys.
• When one of the agent's MCP tools needs a user sign-in, the user signs in through the agent. Direct access to the MCP server is not needed. See Call Tools on the MCP Endpoint.