External Agent Policy and Capabilities

Read an external agent’s public policy before showing controls or starting a workflow. The policy describes which capabilities, stream profiles, output types, host-context fields, and domain tools the agent exposes. If you call prepare() with preferences, build around the negotiated result the server returns rather than the options you asked for.

Check policy at the server-facing integration boundary before showing an action in the app.

Inspect what the agent exposes

Call getEffectivePolicy() for the current agent. Its public shape includes capability flags for messages, conversations, files, artifacts, interactions, and approvals; supported stream profiles; output module types; file and host-context limits; domain tools; rate and spend limits; and the public error-detail setting.

Organize the UI around the task’s required capabilities, not the full list of SDK methods. For example, an attachment control depends on the agent’s file capability and its filePolicy; a workflow that uses a domain tool depends on that tool’s advertised status and operation details. The server applies configured constraints, while the UI prevents people from starting an unsupported path and gives them a clear explanation.

Use negotiated settings

prepare() can request a stream profile, output modules, or provider-grounding display. The returned negotiated object contains the settings that were resolved. Use those values when configuring the view:

const { policy, negotiated } = await client.prepare({
  streamProfile: 'runtime-standard-v1',
  outputModuleTypes: ['citation'],
  providerGroundingDisplay: true,
});

renderWith(negotiated.streamProfile, negotiated.outputModuleTypes);

The SDK guide describes runtime-standard-v1 as the full public runtime event stream, modules-v1 for structured output modules, and chat-legacy-v1 for compatibility with older chat integrations. Treat these names as the documented choices for the current SDK version; do not silently assume the server accepted a preference. See the policy reference for the complete field types.

Design for tools and approvals

Each public domain tool can describe an operation kind, its side-effect class, idempotency, approval requirement, schemas, and status. An operation marked as requiring approval can raise an approval:requested event during streaming and wait for a decision. Keep that pending state visible. An approval request, or an approved decision, does not by itself prove that the operation completed; show success only when the operation’s result confirms it.

This guide covers approval detection and display. The External Agents SDK 0.1.0 declarations expose approval events, but do not specify a dedicated approval-resolution method. The conversation guide documents respondToInteraction() for interactions; it does not establish that an approvalRef can be passed as an interactionRef. Before enabling approval controls, verify the application's supported resolution flow for an authorized reviewer. If no such flow is configured, keep the dependent action unavailable and offer a staff handoff. Do not bypass approval or invent a response payload.

Completed policy check (fictional procurement assistant)
Policy read: messages: true, conversations: true, files: false, artifacts: false.
Negotiation: The request for runtime-standard-v1 and citations returns runtime-standard-v1 with no enabled output modules.
UI: The app shows the conversation composer, hides attachment and artifact controls, and renders no citation panel.
Result: The user can submit a text question; the interface does not promise a feature the policy did not expose.

The example represents one fictional policy response, not a default AgentShelf configuration. A disabled capability results in a capability denial rather than empty data. Handle that state as an unavailable feature, and compare it with the latest policy instead of repeatedly retrying the same call.

Keep policy checks current

Read policy before rendering controls and again when the integration’s operating context changes. Do not cache it longer than the product’s own configuration lifecycle supports. For workspace-backed functions, also check the binding’s enabled capabilities and runtime readiness. For failure triage, follow external-agent integration troubleshooting; for session setup, see embedding an AgentShelf agent.