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 calling, creating and managing agents.

Calling an agent

Send the agent ID as model to POST /v1/responses. Other endpoints, such as /v1/chat/completions, refuse an agent ID.

curl -sS "${API_BASE_URL}/v1/responses" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"model": "acme-ticket-assistant", "input": "Summarize ticket 4711."}'

The response has the same shape as any Responses API response, with the agent ID in model.

An agent request accepts fewer fields than a request to a model. The agent supplies the instructions, tools and sampling parameters, so the caller sends only these:

Field	Value
model	Required. The agent ID.
input	A string, or an array of messages with role: "user". Message content is a string or an array of content parts, such as input_text and input_image. Required unless conversation_id is set.
stream	true to stream server-sent events. Default false.
store	true to start a stored conversation. Default false, unlike direct model requests. See Conversations.
conversation_id	Continue a stored conversation. See Conversations.
chat_mode	true to add Chat's formatting guidance and date. See Chat mode.
mcp_authorizations	OAuth tokens for agent tools that need a user sign-in. See Call Tools on the MCP Endpoint.
metadata, user, safety_identifier, prompt_cache_key	Same meaning as in the OpenAI Responses API.

Any other field is refused with 400 and field "<name>" is not permitted on a preset-agent request. This includes instructions, tools, tool_choice, temperature, top_p and max_output_tokens. To limit the answer length, set Maximum output tokens on the agent; see Locked parameters. max_tokens is a Chat Completions field and is refused too. tenant_id and cache_salt are accepted but ignored.

Ownership

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

• A tenant-owned agent is created by an Editor or Owner of the tenant and belongs to that tenant. Its creator administers it.
• 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

Only a platform-owned agent can be shared. A platform admin can share it with selected tenants, or with everyone. The portal offers sharing only on a platform-owned agent's page.

A tenant-owned agent cannot be shared, and only its own tenant can use it. Over the API, saving selected tenants on one is refused with sharedWith is only valid for platform-owned resources, and saving sharing with everyone is refused with shareToAll is only valid for platform-owned resources. The same refusal applies at creation. When several tenants need the same agent, ask a platform administrator to create it as a platform-owned agent and share it.

Platform agents shared with your tenant

A platform agent that is shared with your tenant is listed in your tenant's Preset Agents list, next to the agents your tenant owns. You can use it from your tenant, but you cannot change it there. Sharing gives use, not management.

The agent's page opens read-only: no Edit button, no Delete button, and no tabs. Below the configuration the page reads This agent is managed outside this tenant. A platform administrator also gets a Manage this agent link to the agent's page under Manage platform. Everyone else is asked to contact a platform administrator.

Someone who may only use the agent sees its description, instructions and tool servers as empty on this page: the platform serves those fields only to administrators of the agent. If you are a platform administrator, open the agent under Manage platform to read them. Output guardrail details are also unavailable in the invoke-only view.

If an agent you expect is not in the list, ask a platform administrator to share it with your tenant, as described under Sharing.

Configuration permissions

When you create an agent, the platform checks that you can use its model and every guardrail's judge model. For a tenant-owned agent, you must also be able to use every tool server. For a platform-owned agent, you need permission to manage each external MCP server; configuring it does not require a selected tenant. RAG deployments still require permission to use them.

When you edit an agent, the platform checks your access to any resources you add or replace. If any check fails, the save is refused with you cannot invoke every configured resource. Expanding access to the agent, through tenant sharing or user and group permissions, checks your access to all its configured resources again.

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.

The base model picker marks a stopped model (stopped) and lists it after models without that mark. An alias has the same mark when its target model is stopped. You can select a stopped model when you create or edit an agent, but calls to the agent fail until a platform administrator starts the model from the Models page.

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.

Description

An agent can carry a short description: a summary, in your own words, of what the agent does. It is written for the people who work with the agent in the portal. It is not part of the prompt — what the model should do belongs in the instructions.

The description is optional and can be at most 4096 characters. You write it on the create form, and you change it later on the agent's page: select the pencil next to Description, edit the text, and select Save changes. An agent with no description shows a dash.

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 description, the display name, the last tool server, or every output guardrail.

Leave hooks out of an edit and the stored guardrails stay as they are. Send hooks with a guardrail list and that list replaces the stored one completely. Send "hooks": {} to clear all guardrails. To change one guardrail, send the full list you want.

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.

Output guardrails

An agent can check its final answer before the caller sees it. Each check is an output guardrail. Another model, the judge, reads the answer and decides whether it may be released. You write the policy the judge applies.

An agent can have up to four guardrails. They run in the order you list them and stop at the first block or error. When a guardrail blocks, the caller gets its block message instead of the answer. If a check fails, the call fails without releasing the protected answer.

Every output guardrail keeps intermediate assistant text, reasoning, tool calls and results private for the whole request. The gateway keeps that context available to the model during execution, then releases only the selected final answer or block message. Annotations and citations are omitted because the judge does not check their text and targets. Trusted status, usage and OAuth recovery errors remain available. The agent's own tools still run, but their calls and results stay private.

With guardrails on, users wait for the agent to finish generating its answer and for the checks to finish before any answer text appears. They receive no incremental answer text, reasoning or tool progress updates during this wait. Chat labels the wait with a Thinking indicator and the elapsed time. The indicator changes to Writing once answer text starts to arrive, and stays until the answer is complete. The final answer or block message then appears all at once.

Streaming API callers receive lifecycle events and content-free keepalives while waiting. These do not report generation or tool progress. After the checks, the gateway serializes the selected final answer or block message into SSE events immediately, without pacing. Calls without guardrails continue to stream answers as they are generated.

In Portal v2, open Add agent or an agent's Edit form and find Output guardrails. Choose Add guardrail, select a judge model and protocol, and enter the policy. Use Move up and Move down to change the check order. The form and detail page explain that output guardrails keep intermediate output private. Use Remove guardrail to remove a check. Saving with every check removed clears the list.

Each guardrail also has a Reasoning effort list and a Block message box. Reasoning effort starts at Low (default). A higher setting gives the judge more time to reason and can delay the answer. Leave Block message empty to use I cannot provide that response. when the check blocks an answer.

The judge picker offers guardrail models and listed aliases whose visible target is a guardrail model. An existing reference stays visible even when it is no longer an option. If the judge list fails to load, saving other fields leaves the guardrails unchanged. The detail page shows the saved checks in order.

The judge picker also marks stopped models (stopped) and lists them last. This includes aliases whose target model is stopped. You can still select and save a stopped judge model. Ask a platform administrator to start it from the Models page before you use the agent: a check cannot run while its judge model is stopped.

If no guardrail models are available to choose, the form shows No guardrail models are available. Existing references are kept. Ask an administrator to make a model of type guardrail available to you by deploying one, adding an external model, or granting access to an existing model. Then select it as the judge for your check.

Over the API, use the agent's hooks.outputGuardrails list. Each guardrail has these fields:

Field	Value
Kind (kind)	Required. HOOK_KIND_MODEL is the only supported value.
Judge model (model.modelId)	Required. A model ID or alias.
Policy (model.instructions)	Required. The instructions the judge uses to check the answer.
Judge protocol (model.judgeProtocol)	Required. Must be JUDGE_PROTOCOL_GPT_OSS_SAFEGUARD.
Reasoning effort (model.reasoningEffort)	Optional. Defaults to low. See the values below.
Block message (blockMessage)	Optional. Empty uses I cannot provide that response.

A judge model alias follows its target, like the agent's own model. Reasoning effort accepts REASONING_EFFORT_LOW, REASONING_EFFORT_MEDIUM, or REASONING_EFFORT_HIGH.

For example, include this configuration in the agent when creating it, or in update when editing it:

{
  "hooks": {
    "outputGuardrails": [
      {
        "kind": "HOOK_KIND_MODEL",
        "model": {
          "modelId": "<judge-model-id>",
          "judgeProtocol": "JUDGE_PROTOCOL_GPT_OSS_SAFEGUARD",
          "instructions": "Block any answer that names an internal hostname.",
          "reasoningEffort": "REASONING_EFFORT_LOW"
        },
        "blockMessage": "I cannot share that."
      }
    ]
  }
}

Models intended for judging are listed by GET /v1/models?type=guardrail, described under Model Gateway.

Each guardrail that runs makes an extra model call. Its input and output tokens count towards the calling tenant's usage, attributed to the judge model. See Tenant Metrics & Usage Tracking.

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	The agent's model, a judge model, or a tool server does not resolve, for example after deletion.

When a guardrail's judge model has been deleted, the API still returns the guardrail, but its model.modelId is empty. The policy and block message are kept, so you can choose another judge model and save the configuration.

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.

Stored conversations retain your messages, eligible model output and executed tool call/result pairs. The gateway also stores the server instructions and effective tool definitions used for each eligible request as private replay context. That context is excluded from conversation-item retrieval, public response fields and content capture. These exclusions do not prevent a model from repeating information from its instructions in an answer.

When output guardrails allow the final answer, eligible intermediate messages, reasoning and executed tool call/result pairs remain available for replay, authorized conversation-item retrieval and forks. Public Responses output and content capture contain only the selected final answer. A blocked request keeps the user input and replacement block message, and discards its private intermediate output. Adding guardrails does not remove older stored messages.

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: the ones you created, and the ones whose admin granted you admin access.

In the portal

Open Preset Agents in the navigation. A tenant's list shows every agent that tenant can call: the agents the tenant owns, and the platform agents shared with it. The list under Manage platform shows the platform-owned agents you can manage. Both lists have the columns Display name, Agent id, Base model, Status, and Access. Select an agent's display name to open its page. To delete an agent, open its page and select Delete there.

Add agent opens the create form. Editors and Owners of the tenant get 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 Configuration permissions.

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 two tabs. General shows the agent itself: the Description at the top, then one Configuration card with the instructions, the base model, the tool servers, output guardrails and locked parameters. Edit sits on that card and opens the fields in place. The base model is a link to that model's own page. Long instructions sit in their own scrolling box, so the card stays short. Users holds the access sections. The chosen tab is part of the page address, so you can bookmark it or send the link to someone else. Delete stays at the top right of the page. Delete asks for confirmation first. After a delete, calls that send the agent's ID stop working.

The sharing controls sit under Access on the Users tab of a platform-owned agent's page, reached through Manage platform. Choosing tenants there needs platform tenant-management access. Without it, saving keeps the shared tenants unchanged. A tenant-owned agent's page has no sharing controls. To give people in your own tenant access to it, use the sections described under Per-agent permissions.

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 a tenant's agent, select the Users tab, and find two sections:

• Administrators — can edit, share and delete the agent, on top of this tenant's owners. They can also invoke it.
• Users — can chat with the agent and call it, but cannot edit or manage it.

Each section has its own table, with the name and whether the entry is a User or a Group. Add administrator and Add user open a picker over the members and groups of the tenant, and every row has a remove button. A platform-owned agent's page has no such sections. See Access to one resource for the full steps.

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 configured tools and instructions apply.

Chat adds its formatting guidance and the current UTC date after the agent's instructions. The agent never uses the tenant's assistant instructions. A call to POST /v1/responses receives the same additions only when it sends chat_mode: true. See Chat mode.

The agent accepts the same kinds of input as its model. Choose a model that accepts images if the people using the agent need to send pictures or screenshots. If the model takes text only, so does the agent, and Chat refuses an image with the reason shown above the message box. See Sending images.

If the agent's model has been deleted, the agent is listed as text in and text out until you point it at another model.

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.