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

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.

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. 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.

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.

The conversation keeps your messages and the agent's answers. The agent's system prompt is never kept and never returned. When an agent has output guardrails, only user input and the selected final answer are stored. Private tool details and reasoning are discarded at the end of the request, so they cannot appear in history or conversation forks. Later requests may repeat tool calls or lack details needed for follow-up questions. Private persistent history is not supported. 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. 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.

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. 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 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.