Run an agent
/api/v1/agents/{agent_id}/runStart an execution of this agent.
The API accepts the request, then runs the work asynchronously. A successful call returns 202 with the run to poll or stream. Authorization, capacity, and budget failures are returned by this request.
An optional Idempotency-Key header makes the start retry-safe: re-presenting the same key returns the existing run rather than starting — and charging for — a second one. The key is scoped to the caller and this agent. Reusing it with different input is rejected with 409.
This root run uses a task timezone. A direct user-session call uses the IANA timezone stored on that session; automation-account and delegated-token calls use UTC. Agents interpret unqualified dates and wall-clock times in that task timezone, and child work and later resumes inherit it. API timestamp fields remain UTC.
artifact_inputs attaches up to 20 ready artifacts the caller can already read. Each entry gives the receiving run a unique alias; include expected_sha256 to require the selected file checksum. Attached files are made available to the run but are not automatically inserted into the model prompt.
A tool_approval_mode of auto or none lowers the run's approvals. Only a user or a delegated token may set it, and when the workspace lets only its owners and admins lower approvals, anyone else is refused with 403. A delegated token counts as a member, never as an admin.
If the agent defines output_schema, platform verification runs only after a successful, non-paused terminal result. The response must be one exact finite JSON object, with no prose or code fence. After secret redaction and control-character sanitization, the object is validated against the supported JSON Schema Draft 2020-12 subset. References must be local and begin with #; validation does not coerce values or insert defaults.
A schema match, with all other required checks passing, completes with verification_status=verified. A mismatch changes the execution to failed and records verification_failed. If execution fails or pauses before the verifier runs, verification remains not_evaluated; a successful run with no applicable verifier completes as unverified.
An agent's optional versioned completion_contract adds checks against the original admitted input, recorded tool results, and current published artifacts. The agent gets a limited number of correction attempts; unresolved requirements fail with verification.completion_failed and verification_failed. These checks validate configured evidence, not subjective output quality, except a rubric check: a separate model grades the final answer against its criteria, and an unmet criterion is a failed required check the agent must correct. A met rubric is recorded as an advisory check and never makes a run verified on its own; if it can't be graded, it is advisory and marked not evaluated.
Set input_data.require_artifact=true when required file delivery is part of the run contract. A committed artifact adds a passed required artifact_requirement check; if none is published after the allowed correction attempts, the run fails with artifact.required_not_published and verification_failed. When an output schema is also configured, both required checks must pass. Attaching or reading an artifact_input does not verify the run's outcome.
Required access
Credentials: automation account, delegated token, user session, user API key
User API keys use the owner’s current permissions, subject to any key restrictions. Capability scopes below apply to automation account keys and delegated tokens.
Scope: agents:invoke
The agent must be shared with the organization, or granted to the calling principal if it is restricted. A viewer can't run agents, not even one they own or hold an invoke grant on.
A user-owned key prefixed gsmc_uk_, bound to one organization. It follows its owner's current membership, role and resource permissions, optionally restricted to read-only access. No X-Org-Id header is needed; a conflicting organization is rejected. Credential creation, personal connection setup and human attestations require a signed-in session. Runs are private to the calling user; sharing an agent grants access to your own personal memory of it, never to the agent's own memory.
In: header
Path Parameters
uuidHeader Parameters
Makes this start retry-safe. Generate one stable value per intended execution and reuse it only when retrying that same execution: the key is scoped to the caller and the target resource, and re-presenting it returns the existing run instead of starting a second one. The same key with different input answers 409.
Selects the active organization for a direct user session that has more than one membership. Automation account keys and delegated tokens are each bound to one organization and ignore it.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Request body for executing an agent.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/api/v1/agents/497f6eca-6276-4993-bfeb-53cbbbba6f08/run" \ -H "Authorization: Bearer $GUEST_MACHINES_API_KEY" \ -H "Idempotency-Key: 9f8c2b7a-1d3e-4f5a-8b6c-2e1d0a9f8c7b" \ -H "Content-Type: application/json" \ -d '{ "input_data": { "repository": "acme/checkout", "since": "2026-07-01" }, "message": "Summarize the release-blocking issues.", "artifact_inputs": [ { "artifact_id": "10000000-0000-4000-8000-000000000001", "alias": "release-evidence", "expected_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } ], "project_tag": "checkout-rewrite" }'{ "run": { "id": 1, "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978", "invocable_type": "agent", "workflow_id": "03e70e31-d7a4-4401-a629-6a4b6096cdfe", "enclosing_workflow_run_id": 1, "actor_principal_type": "agent", "service_principal_id": "0d57b427-9ed2-4a5e-b0bd-32c8ce299b8e", "oauth_client_id": "727760ca-b97d-449c-90e5-7773c8142d5d", "parent_run_id": 1, "root_run_id": 1, "call_depth": 0, "agent_config_revision": 1, "agent_config_digest": "string", "tool_approval_mode": "auto", "tool_approval_mode_revision": 1, "status": "awaiting_plan_approval", "created_at": "2019-08-24T14:15:22Z", "started_at": "2019-08-24T14:15:22Z", "completed_at": "2019-08-24T14:15:22Z", "duration_seconds": 0, "last_heartbeat": "2019-08-24T14:15:22Z", "queued_since": "2019-08-24T14:15:22Z", "last_action": { "action": "answered", "at": "2019-08-24T14:15:22Z", "by_principal_type": "agent", "by_name": "string", "by_run_starter": true }, "input_data": {}, "output_data": {}, "artifacts": [ {} ], "verification_status": "not_evaluated", "verification_summary": "string", "verification_checks_passed": 0, "verification_checks_total": 0, "verification_evaluated_at": "2019-08-24T14:15:22Z", "error": "string", "error_category": "string", "error_code": "string", "error_retryable": true, "pause_reason": { "category": "manual", "code": "string", "message": "string" }, "limit_detail": { "error": "limit_exceeded", "limit_type": "account.needs_approval", "scope": "agent", "message": "string", "scope_id": "string", "limit": 0, "actual": 0, "retry_after_seconds": 0, "resets_at": "2019-08-24T14:15:22Z" }, "tool_retry_intervention": { "code": "string", "message": "string", "retryable": true, "suggested_action": "string", "tool_label": "string", "policy_event_type": "string", "attempt_count": 1, "failure_class": "authentication", "last_error_code": "string", "retry_disposition": "authentication_required", "circuit_state": "closed", "retry_not_before": "2019-08-24T14:15:22Z" }, "tool_outcome_blocker": { "blocker_id": "string", "reason": "tool.outcome_uncertain", "retry_not_before": "2019-08-24T14:15:22Z", "review": { "schema_version": 1, "review_core": { "schema_version": 1, "action_label": "string", "target_summary": "string", "attempted_at": "2019-08-24T14:15:22Z", "attempt_count": 1, "failure_class": "authentication", "error_code": "string", "uncertainty_reason": "string", "evidence": [ { "kind": "string", "label": "string", "content_digest": "stringstringstringstringstringstringstringstringstringstringstringstrin" } ] }, "attestable": true, "review_digest": "string", "evidence_links": [ { "kind": "tool_call_audit", "label": "string", "resource_id": "string" } ] }, "resolution_committed": false, "resume_pending": false, "resolution_id": "e25ae328-69b8-4e08-9f09-52d881051e39", "resolution": "abandon_operation" }, "tool_outcome_wake_state": "string", "tool_outcome_resume_retryable": false, "tool_calls_count": 0, "tool_attempts_count": 0, "tokens_used": 0, "input_tokens": 0, "output_tokens": 0, "cache_read_input_tokens": 0, "cache_creation_input_tokens": 0, "platform_model_tokens": 0, "model": "string", "cost_usd": 0, "cost_pricing_fallback": true, "sandbox_duration_ms": 0, "sandbox_cost_cents": 0, "sandbox_id": "string", "desktop_stream_url": "string", "child_group_id": 1, "child_scope_key": "string", "child_scope_label": "string", "child_group_count": 0, "project_tag": "string", "ticket_tag": "string", "cost_center_tag": "string" }}Update an agent PATCH
Update selected fields of an agent configuration. Omitted fields are unchanged. Collection fields such as `configured_tools` and `mcp_server_ids` replace the complete collection when present; send an empty collection to clear one.
List runs for an agent GET
List executions of this agent, newest first.