Policy and capabilities

Every external agent publishes a public policy: what it can do, which stream profiles it speaks, what host context it accepts, and what its limits are. Read it before you build UI around a feature — capabilities are per agent, and calling into a disabled one returns a stable error rather than degrading silently.

Reading the policy

const policy = await client.getEffectivePolicy();

if (policy.capabilities.files) {
  showAttachmentButton();
}

PublicExternalAgentPolicy:

Field	Meaning
capabilities	Booleans for messages, conversations, files, artifacts, interactions, approvals.
streamProfiles / defaultStreamProfile	Profiles the agent accepts, and the one used when you do not ask.
outputModuleTypes	Structured output module types the agent may emit.
providerGroundingDisplay	Whether provider grounding may be shown to the user.
domainTools	Domain tools exposed to this agent, as PublicDomainTool.
filePolicy	upload, read, maxUploadBytes, allowedMimeTypes.
hostContextPolicy	acceptedFields and maxTotalBytes.
rateLimits / spendLimits	Enforced server-side.
publicErrorDetail	minimal, standard, or diagnostic — how verbose public errors are.
sdk.minVersion	Minimum SDK version the agent requires, or null.

Negotiating

prepare() proposes a configuration and returns what the server actually granted. Always read the negotiated values back rather than assuming your request was honoured:

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

renderWith(negotiated.streamProfile, negotiated.outputModuleTypes);

negotiated reports the resolved streamProfile, outputModuleTypes, and providerGroundingDisplay. Full type: ExternalAgentPrepareResult.

Stream profiles

Profile	Use
runtime-standard-v1	The full public runtime event stream. Start here.
modules-v1	Structured output modules.
chat-legacy-v1	Compatibility profile for older chat integrations.

Domain tools

policy.domainTools describes the domain operations available to the agent. Each entry carries a publicName, an operation block (kind, sideEffectClass, idempotency, approvalRequired), optional input/output schemas, and a status.

operation.approvalRequired is the one to design for: those tools raise an approval:requested event mid-stream and wait. See Conversations and streaming.

Disabled capabilities

Calling into a capability the policy has turned off fails with a stable 403 unsupported_capability error — it does not return empty data. Gate the UI on capabilities rather than catching the error as flow control.