Invoke an agent

Programmatic invocation should behave like calling a typed function: provide valid input, receive an execution identity, and observe the run until it reaches a terminal state.

Define a stable contract

Before integrating, make the agent's required input and output explicit. Avoid parsing prose when a structured schema can represent the result.

The caller should know:

• which agent or published interface it is invoking;
• the required input shape;
• whether execution is synchronous, streamed, or asynchronous;
• how to observe and cancel the run;
• which terminal states are possible.

Know what an output schema guarantees

Agent and team contracts use a bounded, object-rooted profile of JSON Schema Draft 2020-12. A configured schema must be a JSON object whose root declares "type": "object". The $schema keyword is optional; when present, it must identify Draft 2020-12. $ref and $dynamicRef may point to definitions inside the same schema with a # reference. Guest Machines never retrieves a remote schema.

An otherwise successful model response must be one exact, finite JSON document. Surrounding prose, Markdown fences, trailing content, duplicate object keys, and non-finite numbers such as NaN do not count as structured output. Validation uses JSON types exactly: it does not turn strings into numbers, remove unknown fields, or insert missing fields. In particular, JSON Schema's default keyword is documentation and does not supply a value. Additional object properties are allowed by JSON Schema unless your contract sets "additionalProperties": false.

Format assertions are enforced for color, date, date-time, duration, email, hostname, idn-email, idn-hostname, ipv4, ipv6, iri, iri-reference, json-pointer, regex, relative-json-pointer, time, uri, uri-reference, uri-template, and uuid. An unknown format makes the schema invalid instead of silently becoming an annotation.

Invalid or unbounded schemas are rejected when the agent or team is saved. The profile allows at most:

• 64 KiB of canonical schema JSON;
• 32 levels of schema nesting;
• 2,048 schema nodes;
• 512 declared properties across the schema;
• 2,048 characters in one description; and
• 1,024 characters in one pattern.

Provider-native structured output helps the model produce the right shape, but it is not the verifier. After generation, Guest Machines validates the exact result locally against the original contract, including constraints that a model provider could not enforce while generating.

Treat execution and verification as separate outcomes. status=completed means the execution lifecycle finished; it does not prove that the returned result is correct. Inspect verification_status as well:

• verified means every required platform check passed;
• unverified means execution completed without evidence from a required verifier;
• verification_failed means at least one required check failed;
• not_evaluated means no verification result exists yet, including when execution stops before a verifier can run.

Output-schema verification runs only after execution has produced an otherwise successful terminal result. A schema mismatch changes the run to status=failed with verification_status=verification_failed; it is not a completed but partially valid result. A pause, cancellation, provider outage, tool failure, or other operational failure stops before this check and remains not_evaluated.

Verification is scoped to the checks that ran. Passing output-schema validation proves that the JSON structure met the declared contract. It does not prove that its facts are true, that its reasoning is sound, or that it completed the requested task well.

Completion evidence records the schema and output as SHA-256 fingerprints. On a failure it records safe paths and constraint names for at most 20 validation errors; rejected output values are not copied into evidence.

Scope the machine caller

Use a service principal with the minimum invoke and run-observation scopes. A successful authentication does not bypass resource visibility or allowlist rules: the agent being invoked must be shared with the organization, or explicitly granted to the principal, because a service principal can never reach a private resource. See authentication.

Make starts retry-safe

For endpoints that accept Idempotency-Key, generate one stable value per intended execution. Reuse it only when retrying the same payload. Reusing a key with different input should be treated as a conflict.

Where the details are

Run an agent documents the request and response, the failure modes, and the scope it needs, with request samples in seven languages. Runs covers observing execution to a terminal state.

Team and pipeline invocation work the same way with one exception worth knowing before you design around them: both spawn work on an acting user's behalf, so they need a delegated token. A service-principal key authenticates, passes its scope check, and is then refused at admission.

First-party SDKs are not published yet. Operation identifiers in the reference are frozen, so a client generated from the contract keeps working.