> ## Agent Instructions > To act on a user's behalf in Guild, use the Guild REST API at https://api.guild.ai/v1. > The OpenAPI spec is unauthenticated: https://docs.guild.ai/openapi.json (or openapi.yaml). > Authenticate with an account API key, sent as HTTP Basic (key id as username, secret as password) or as `Authorization: Bearer :`. See https://docs.guild.ai/api-reference/introduction#authentication. > To run one agent on demand without account-wide access, use an API trigger instead: https://docs.guild.ai/platform/api-triggers. > To search these docs from an MCP client, connect to https://docs.guild.ai/mcp. The full page index is https://docs.guild.ai/llms.txt. # Create a skill owned by an account Source: https://docs.guild.ai/api-reference/accounts/create-a-skill-owned-by-an-account /api-reference/openapi.yaml post /accounts/{account_id_or_name}/skills Requires `skills:write`. A key cannot create a *public* skill even with `skills:write` -- publishing is admin-only. # Get a user Source: https://docs.guild.ai/api-reference/accounts/get-a-user /api-reference/openapi.yaml get /users/{user_id_or_name} # Get an organization Source: https://docs.guild.ai/api-reference/accounts/get-an-organization /api-reference/openapi.yaml get /organizations/{org_id_or_name} # Get the identity of the calling credential Source: https://docs.guild.ai/api-reference/accounts/get-the-identity-of-the-calling-credential /api-reference/openapi.yaml get /me An API key gets its own record, including the name of the account that owns it. An OAuth token gets the user it acts as, the client that holds it, and the scopes it was granted. # List a user's organization memberships Source: https://docs.guild.ai/api-reference/accounts/list-a-users-organization-memberships /api-reference/openapi.yaml get /users/{user_id_or_name}/organizations # List an account's integration credentials Source: https://docs.guild.ai/api-reference/accounts/list-an-accounts-integration-credentials /api-reference/openapi.yaml get /accounts/{account_id_or_name}/credentials # List an account's skills Source: https://docs.guild.ai/api-reference/accounts/list-an-accounts-skills /api-reference/openapi.yaml get /accounts/{account_id_or_name}/skills Requires `skills:read`. # List an account's workspaces Source: https://docs.guild.ai/api-reference/accounts/list-an-accounts-workspaces /api-reference/openapi.yaml get /accounts/{account_id_or_name}/workspaces Requires `workspaces:read`. A workspace with restricted membership (`should_restrict_members`) never appears here for an account key, regardless of scope -- that restriction narrows the workspace to its member roster, and a key can't be a member. # List an organization's invitations Source: https://docs.guild.ai/api-reference/accounts/list-an-organizations-invitations /api-reference/openapi.yaml get /organizations/{org_id_or_name}/invitations # List an organization's members as users Source: https://docs.guild.ai/api-reference/accounts/list-an-organizations-members-as-users /api-reference/openapi.yaml get /organizations/{org_id_or_name}/members # List an organization's memberships Source: https://docs.guild.ai/api-reference/accounts/list-an-organizations-memberships /api-reference/openapi.yaml get /organizations/{org_id_or_name}/memberships # List organization invitations sent to the current user Source: https://docs.guild.ai/api-reference/accounts/list-organization-invitations-sent-to-the-current-user /api-reference/openapi.yaml get /me/invitations # List organization invitations sent to the current user's email Source: https://docs.guild.ai/api-reference/accounts/list-organization-invitations-sent-to-the-current-users-email /api-reference/openapi.yaml get /me/email-invitations These are organization invitations sent to the user's email address, which can be accepted at sign-up. Returns pending invitations unless ``status`` asks for another status. # List the current user's organization memberships Source: https://docs.guild.ai/api-reference/accounts/list-the-current-users-organization-memberships /api-reference/openapi.yaml get /me/organizations # Classify each of a version's tools as read or write Source: https://docs.guild.ai/api-reference/agents/classify-each-of-a-versions-tools-as-read-or-write /api-reference/openapi.yaml get /versions/{version_id}/tool-access Integration tools resolve to "read" or "write" from their underlying operation's HTTP method (or MCP hint); built-in and custom tools are reported as "unknown". # Commit a new version of an LLM agent with the given tools Source: https://docs.guild.ai/api-reference/agents/commit-a-new-version-of-an-llm-agent-with-the-given-tools /api-reference/openapi.yaml post /agents/{agent_id_or_name}/configure-llm Requires `agents:write`. Writes a new committed version of an LLM agent from a system prompt, description, and tool list. # Create an agent Source: https://docs.guild.ai/api-reference/agents/create-an-agent /api-reference/openapi.yaml post /agents Requires `agents:write`. # Create an agent version Source: https://docs.guild.ai/api-reference/agents/create-an-agent-version /api-reference/openapi.yaml post /agents/{agent_id_or_name}/versions # Get an agent Source: https://docs.guild.ai/api-reference/agents/get-an-agent /api-reference/openapi.yaml get /agents/{agent_id_or_name} No key required for a public agent. A private agent needs `agents:read` on a key belonging to its owner account, or the read 404s -- a denied read looks identical to a nonexistent agent. # Get an agent version Source: https://docs.guild.ai/api-reference/agents/get-an-agent-version /api-reference/openapi.yaml get /versions/{version_id} # Get an agent version's source files Source: https://docs.guild.ai/api-reference/agents/get-an-agent-versions-source-files /api-reference/openapi.yaml get /versions/{version_id}/code # Get latest publish job for an agent version Source: https://docs.guild.ai/api-reference/agents/get-latest-publish-job-for-an-agent-version /api-reference/openapi.yaml get /versions/{version_id}/publish/job # Get latest validation job for an agent version Source: https://docs.guild.ai/api-reference/agents/get-latest-validation-job-for-an-agent-version /api-reference/openapi.yaml get /versions/{version_id}/validation/job Returns either VALIDATION or PUBLISH jobs (publish jobs include validation). # List a version's resolved tools: integration, sub-agent or service Source: https://docs.guild.ai/api-reference/agents/list-a-versions-resolved-tools:-integration-sub-agent-or-service /api-reference/openapi.yaml get /versions/{version_id}/tools Empty for versions built before tools were resolved. # List all jobs for an agent version Source: https://docs.guild.ai/api-reference/agents/list-all-jobs-for-an-agent-version /api-reference/openapi.yaml get /versions/{version_id}/jobs # List an agent's versions Source: https://docs.guild.ai/api-reference/agents/list-an-agents-versions /api-reference/openapi.yaml get /agents/{agent_id_or_name}/versions Requires `agents:read`. Also reachable with an OAuth user token that holds `agents:read`; a token without it gets a `404` on a private agent. # List and search agents Source: https://docs.guild.ai/api-reference/agents/list-and-search-agents /api-reference/openapi.yaml get /agents No key required to see public agents. With a key holding `agents:read`, the results also include the account's own private agents. # List publish steps for an agent version Source: https://docs.guild.ai/api-reference/agents/list-publish-steps-for-an-agent-version /api-reference/openapi.yaml get /versions/{version_id}/publish/steps # List validation steps for an agent version Source: https://docs.guild.ai/api-reference/agents/list-validation-steps-for-an-agent-version /api-reference/openapi.yaml get /versions/{version_id}/validation/steps Returns steps from either VALIDATION or PUBLISH jobs. # Publish an agent version Source: https://docs.guild.ai/api-reference/agents/publish-an-agent-version /api-reference/openapi.yaml post /versions/{version_id}/publish Requires `agents:write`. # Revalidate a version Source: https://docs.guild.ai/api-reference/agents/revalidate-a-version /api-reference/openapi.yaml post /agents/{agent_id_or_name}/versions/{version_id}/revalidate # Run the checks a version must pass before publishing Source: https://docs.guild.ai/api-reference/agents/run-the-checks-a-version-must-pass-before-publishing /api-reference/openapi.yaml post /versions/{version_id}/publish_pre_checks # Unpublish an agent version Source: https://docs.guild.ai/api-reference/agents/unpublish-an-agent-version /api-reference/openapi.yaml post /versions/{version_id}/unpublish # Update an agent's visibility, archive state or pin Source: https://docs.guild.ai/api-reference/agents/update-an-agents-visibility-archive-state-or-pin /api-reference/openapi.yaml patch /agents/{agent_id_or_name} # Enroll a customer connector and issue its credentials Source: https://docs.guild.ai/api-reference/connectors/enroll-a-customer-connector-and-issue-its-credentials /api-reference/openapi.yaml post /customer_connectors/enroll # Renew an enrolled customer connector's credentials Source: https://docs.guild.ai/api-reference/connectors/renew-an-enrolled-customer-connectors-credentials /api-reference/openapi.yaml post /customer_connectors/renew # Agent sessions API Source: https://docs.guild.ai/api-reference/conversations Start a session with a Guild agent using an account API key, then poll or stream its replies over a WebSocket and send follow-up messages. An account API key can hold a full conversation with an agent: start a chat, read the agent's replies, and send follow-ups. This is the surface a partner backend integrates against most often, so the whole flow is spelled out here — the underlying endpoints are also documented individually under **Sessions** in the sidebar. This is a different flow from [API triggers](/platform/api-triggers). A trigger API key runs one agent on demand and is scoped to a single trigger. An account key holds an open-ended conversation with any agent installed in the account's workspaces, scoped by `sessions:write`. ## Start a chat ```http theme={null} POST /workspaces/{workspace_id_or_name}/sessions ``` Requires `sessions:write` on a workspace the key's account owns. The scope is deliberately `sessions`, not `workspaces`, so workspace scope alone can't quietly grant conversations. #### Request body | Field | Type | Required | Description | | - | - | - | - | | `session_type` | string | Yes | `"chat"` for a conversation. A key may also create `agent_test` sessions, which run one agent version; `api_trigger` is `403` for a key. | | `agent_id` | string (uuid) | Yes | The agent to converse with. | | `initial_prompt` | string | Yes | The first message. The agent begins executing it immediately. | #### Example ```bash theme={null} curl -X POST https://api.guild.ai/v1/workspaces/acme~support/sessions \ -u ":" \ -H "Content-Type: application/json" \ -d '{ "session_type": "chat", "agent_id": "", "initial_prompt": "Summarize open tickets tagged urgent." }' ``` #### Response Returns `201` with the session. The key is recorded as the session's `initiator`, serialized as `type: "api_key"`: ```json theme={null} { "id": "3fa2c1e0-9b4e-4b3a-8f1a-2b6b8b6a2b31", "workspace_id": "8c1e2f3a-4b5c-4d6e-9f0a-1b2c3d4e5f6a", "initiator_id": "", "name": null, "created_at": "2026-08-27T14:02:11.483Z", "updated_at": "2026-08-27T14:02:11.483Z" } ``` ## Read the conversation ```http theme={null} GET /sessions/{session_id}/events?from_id= ``` Requires `workspaces:read`, plus `agents:read` when the session ran an agent — see [List session events](/api-reference/sessions/list-session-events). Events default to newest-first (`sort_by=-id`) with a limit of 20, so a naive read returns the tail of the conversation in reverse. For polling, pass `from_id`: it's an exclusive cursor (`id > from_id`), so each poll returns only what happened since the last one. Event ids are UUIDv7 and therefore time-ordered. The agent's reply arrives as a `runtime_done` event whose `content.text` carries the message. One turn can emit **several** `runtime_done` events, because subtasks and tool runs complete with empty content (`{}`) before the top-level turn does. Read the reply from the `runtime_done` that carries `content.text`, not simply the first one to appear. Events persist when a turn completes, not while the model is streaming — a poll during generation returns nothing new until the turn finishes. If you would rather not poll, the same events are available over a WebSocket — see [Stream the conversation](#stream-the-conversation). #### Example ```bash theme={null} curl -u ":" \ "https://api.guild.ai/v1/sessions//events?from_id=" ``` #### Response ```json theme={null} { "items": [ { "id": "9d2f4a1b-6e3c-4a2f-8b1d-5c6e7f8a9b0c", "type": "runtime_done", "content": { "text": "Three tickets are tagged urgent: #482, #491, #503." }, "task_id": "f1a04e6c-7b2a-4e1d-9c3a-1a2b3c4d5e6f", "created_at": "2026-08-27T14:02:39.221Z", "updated_at": "2026-08-27T14:02:39.221Z" } ], "pagination": { "total_count": 1, "limit": 20, "offset": 0, "has_more": false } } ``` Poll again with `from_id=9d2f4a1b-...` to only see events after this one. ## Stream the conversation Instead of polling, connect to the session events WebSocket and receive each event as it is written. ```text theme={null} wss://api.guild.ai/v1/sessions/{session_id}/events/ws ``` Requires the same scopes as the polling read: `workspaces:read`, plus `agents:read` when the session ran an agent. Privacy is evaluated identically too — a session the key cannot see closes the connection with `404` rather than reporting an authorization error. Authenticate with the same API key, sent as an `Authorization: Basic` header on the connection request. **A socket opened without `from_id` carries only events created after the connection opens.** It does not replay anything that already happened, so a client that connects after starting a session can silently miss the agent's reply. Pass `from_id` with the last event id you processed — the socket then replays the backlog after that cursor before switching to live delivery. That is also how you resume after a reconnect. The `Authorization` header is the only way to authenticate this connection. A browser's built-in `WebSocket` cannot set request headers, so connect from a server-side or native client instead. #### Query parameters | Parameter | Description | | - | - | | `from_id` | Replay events after this event id, then stream live. Omit it and you get live events only. Ephemeral draft ids are rejected — use the id of a persisted event. | | `types` | Comma-separated event types to receive. Omit it for every type. An unrecognized type is rejected with a message listing the valid ones. | #### Example ```bash theme={null} websocat -H "Authorization: Basic $(printf '%s' ':' | base64)" \ "wss://api.guild.ai/v1/sessions//events/ws?from_id=" ``` Each message is a single event, in the same shape as one entry of the `items` array returned by `GET /sessions/{session_id}/events`. This endpoint is not listed in the sidebar or in `openapi.yaml`: OpenAPI cannot describe WebSockets. It is part of the public API all the same. ## Send a follow-up ```http theme={null} POST /sessions/{session_id}/events ``` Requires `sessions:write` — see [Send a message to a session](/api-reference/sessions/send-a-message-to-a-session). The message is authored by the key itself (`author.type: "api_key"`); a key may never author as anyone else. The `agent_id` field is accepted but ignored for a key — it only retargets for user viewers — so a key cannot switch which agent answers mid-conversation. Start a new session instead. #### Example ```bash theme={null} curl -X POST https://api.guild.ai/v1/sessions//events \ -u ":" \ -H "Content-Type: application/json" \ -d '{"content": "What about tickets tagged high, not just urgent?", "mode": "text"}' ``` Read the agent's reply the same way as above — poll `GET /sessions/{session_id}/events?from_id=...` until a new `runtime_done` event appears. ## Containment A key converses only in the chat sessions it initiated. Posting into any other session — another key's chat, a person's chat, a trigger session — is `404`, not `403`: a key cannot inject messages into a human's conversation, and cannot even learn that the other session exists. Reading is broader than writing: with `workspaces:read`, a key can read every session in its account's unrestricted workspaces, it just cannot speak in them. # List the tools an integration provides Source: https://docs.guild.ai/api-reference/integrations/list-the-tools-an-integration-provides /api-reference/openapi.yaml get /integrations/{integration_id_or_name}/tools # Guild API overview Source: https://docs.guild.ai/api-reference/introduction Get started with the Guild public API: base URL, authentication with account API keys, scopes, request and response conventions, and error codes. The Guild public API lets external code — partner integrations, scripts, CI pipelines — act on a Guild account programmatically: hold a conversation with an agent, read agents and skills, create workspaces, publish agent versions, schedule an agent with a [time trigger](/platform/schedule-triggers#with-the-public-api), and read session activity. This is a different surface from the one described in [API triggers](/platform/api-triggers). API triggers use a **trigger API key**, scoped to a single trigger, to run one agent on demand. The public API described here uses an **account API key**, scoped to everything the key's scopes allow across the whole account, to start and hold full conversations with any agent in the account's workspaces, and to automate broader account and workspace management. ## Conversations A key can hold a full conversation with an agent: start a chat, read the agent's replies, and send follow-ups. This is the surface a partner backend integrates against most often, so the whole flow is spelled out on its own page — see [Conversations](/api-reference/conversations). Session events can be polled or streamed over a WebSocket. The WebSocket is part of the public API but does not appear in the sidebar, because OpenAPI cannot describe WebSockets — see [Stream the conversation](/api-reference/conversations#stream-the-conversation). ## Base URL ```text theme={null} https://api.guild.ai/v1 ``` You can explore the API before you create a key. Both of these are unauthenticated: * **OpenAPI spec** — [`https://api.guild.ai/v1/openapi.yaml`](https://api.guild.ai/v1/openapi.yaml), the machine-readable spec to import into an API client or code generator. * **API reference** — [`https://api.guild.ai/v1/docs`](https://api.guild.ai/v1/docs), the spec rendered as a browsable reference. ## Authentication Every request presents the API key one of two ways: as HTTP Basic Authentication, with the key's ID as the username and its secret as the password, or as a Bearer token that carries the whole `:` string in the `Authorization` header. ```bash theme={null} # HTTP Basic Authentication curl -u ":" https://api.guild.ai/v1/agents # Bearer token curl -H "Authorization: Bearer :" https://api.guild.ai/v1/agents ``` The secret is shown exactly once, when the key is created. Settings presents it as a single string: the key id, a colon, then the secret (which starts with `glda_`). That whole string is exactly what `curl -u` takes, and it is exactly the Bearer token to send, so there is no need to split it. ### Create a key Go to [app.guild.ai](https://app.guild.ai), open the account (user or organization) you want the key to act as, and go to **Settings**. Give it a name and choose its scopes. Copy the `:` string shown. It won't be shown again. ### With the CLI ```bash theme={null} guild api-key create --owner --name "CI key" --scopes "agents:write,workspaces:read" # prints id:secret once guild api-key list --owner guild api-key delete ``` `--owner` defaults to the current user's account. `--scopes` takes comma-separated `:` pairs. A key created without `--scopes` authenticates but reaches nothing; every request it makes is denied. Always pass the scopes the key needs. ### MCP clients Model Context Protocol (MCP) clients such as Claude or Cursor authenticate with OAuth instead of an account API key. A client registers itself with [dynamic client registration](https://www.rfc-editor.org/rfc/rfc7591) (RFC 7591) by calling [`POST /oauth/register`](/api-reference/oauth/register-an-oauth-client), so nobody has to add it by hand. A client registered this way is public: it holds no secret and proves itself with PKCE (Proof Key for Code Exchange) on each authorization. Clients find the registration, authorization, and token endpoints through [OAuth discovery](/api-reference/oauth-discovery). ## Scopes A key's access is limited to the scopes you grant it when you create it. A scope is a `(group, access)` pair: | Group | What it covers | | - | - | | `agents` | Reading agents with `read`; creating agents, configuring an LLM agent (system prompt, mode, tools), and publishing versions with `write` | | `sessions` | Reading session status, events, tasks, and runtimes with `read`; starting a chat and sending follow-ups with `write` — see [Conversations](/api-reference/conversations) | | `workspaces` | Reading workspaces, listing a workspace's sessions, and listing its installed agents (which also requires `agents:read`) with `read`; creating workspaces and installing, updating, or removing a workspace's agents with `write`. Changing a workspace's agents needs `workspaces:write`, not `agents:write`, because it changes the workspace. | | `skills` | Reading skills with `read`; creating skills and skill versions with `write` | | `integrations` | Attaching an existing credential to a workspace agent, or minting a new one, with `write`. Minting also needs `workspaces:read`: without it the agent lookup returns `404` before the scope check runs. Minting takes an `auth_config_id`, shown as **ID** in the Authentication card of the integration's Configuration tab | | `tool_call` | Listing the tools an MCP gateway profile exposes with `read`; running them with `write` | `access` is `read` or `write`; `write` implies `read`. A key created with no scopes can authenticate and call [`GET /me`](/api-reference/accounts/get-the-identity-of-the-calling-credential), which needs no scope, but reaches nothing else. Each endpoint in this reference lists the scope it requires. A scope only grants access to entities the key's account can already see or own. It never lets a key reach another account's private data, and it can't act as a person — for example, an `agents:write` key can create and publish agents, but only an admin can make one public. ## Request conventions **Ids and names are interchangeable.** Wherever a request names another entity (a path segment like `{workspace_id_or_name}`, or an `owner_id` field), the account or entity **name** works as well as the UUID. **`owner_id` defaults to the key's account.** On create endpoints where it is optional (creating an agent, for example), omit it and the key's own account owns the result. There is no need to look up an account UUID. **The id you need next is the top-level one.** Responses embed related entities: an install response contains the agent, the workspace, and their owners, each with an `id` of its own. The id of the thing the call created is always the response's **top-level** `id` field; ids inside nested objects identify those other entities. ## Response conventions **List endpoints** return a paginated envelope: ```json theme={null} { "items": [ ], "pagination": { "total_count": 42, "limit": 20, "offset": 0, "has_more": true } } ``` Pass `limit` (default `20`, max `1000`) and `offset` (default `0`) as query parameters to page through results. **Errors** return the relevant `4xx` status with a JSON body: ```json theme={null} { "error": "NotFound", "message": "Workspace not found" } ``` | Status | Meaning | | - | - | | `401` | Missing or invalid credentials. | | `403` | Authenticated, but the key's scopes (or the account's permissions) don't allow this action. | | `404` | The resource doesn't exist, or exists but the key can't see it — Guild returns 404 rather than 403 for reads, so a denied read is indistinguishable from an absent one. On a write, a 404 usually means an id in the path or parameters doesn't match anything the key can see; check each id against the response it came from. | | `400` | The request body or parameters are invalid. | For each error name and message, its cause and the fix, see [Errors and troubleshooting](/reference/errors). # OAuth discovery Source: https://docs.guild.ai/api-reference/oauth-discovery The metadata documents MCP clients read to find Guild's OAuth endpoints, scopes, and PKCE requirements. Guild publishes OAuth 2.0 metadata so Model Context Protocol (MCP) clients such as Claude or Cursor can configure themselves. A client reads the metadata, registers itself, and runs the authorization code flow without any manual setup. Both metadata documents are public. You don't need credentials to read them. OAuth is for MCP clients acting on behalf of a person. To call the REST API from your own code, use an account API key instead. See [Authentication](/api-reference/introduction#authentication). ## Authorization server metadata The authorization server metadata follows [RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414). It lives at the domain root, not under `/v1`: ```bash theme={null} curl https://api.guild.ai/.well-known/oauth-authorization-server ``` | Field | Value | Description | | - | - | - | | `issuer` | `https://api.guild.ai` | The authorization server's issuer identifier. | | `authorization_endpoint` | `https://api.guild.ai/v1/oauth/authorize` | Where the client sends the person to approve access. See [`GET /oauth/authorize`](/api-reference/oauth/start-an-oauth-authorization-by-redirecting-to-the-consent-page). | | `token_endpoint` | `https://api.guild.ai/v1/oauth/token` | Where the client exchanges an authorization code or refresh token for an access token. See [`POST /oauth/token`](/api-reference/oauth/exchange-an-authorization-code-or-refresh-token-for-an-access-token). | | `registration_endpoint` | `https://api.guild.ai/v1/oauth/register` | Where the client registers itself with dynamic client registration. See [`POST /oauth/register`](/api-reference/oauth/register-an-oauth-client). | | `response_types_supported` | `["code"]` | Guild supports the authorization code flow only. | | `grant_types_supported` | `["authorization_code", "refresh_token"]` | The grant types the token endpoint accepts. | | `code_challenge_methods_supported` | `["S256"]` | Every authorization must use PKCE (Proof Key for Code Exchange) with SHA-256. | | `token_endpoint_auth_methods_supported` | `["none"]` | Clients are public. They hold no secret and prove themselves with PKCE instead. | | `scopes_supported` | `:` strings | The scopes a client can request, such as `agents:read` or `workspaces:write`. See [Scopes](/api-reference/introduction#scopes). | Example response: ```json theme={null} { "issuer": "https://api.guild.ai", "authorization_endpoint": "https://api.guild.ai/v1/oauth/authorize", "token_endpoint": "https://api.guild.ai/v1/oauth/token", "registration_endpoint": "https://api.guild.ai/v1/oauth/register", "response_types_supported": ["code"], "grant_types_supported": ["authorization_code", "refresh_token"], "code_challenge_methods_supported": ["S256"], "token_endpoint_auth_methods_supported": ["none"], "scopes_supported": ["agents:read", "agents:write", "sessions:read", "sessions:write", "workspaces:read", "workspaces:write"] } ``` The example shortens `scopes_supported`. Read the live document for the full list rather than hardcoding it. ## Protected resource metadata Each OAuth-protected resource also publishes [RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728) metadata. It names the authorization server and the scopes that resource accepts. The path is the resource's own path, appended to `/.well-known/oauth-protected-resource`: ```bash theme={null} curl https://api.guild.ai/.well-known/oauth-protected-resource/mcp ``` ```json theme={null} { "resource": "https://api.guild.ai/mcp", "authorization_servers": ["https://api.guild.ai"], "bearer_methods_supported": ["header"], "scopes_supported": ["agents:read", "agents:write", "sessions:read", "workspaces:read"] } ``` A client usually finds this document from a `401` response. The response's `WWW-Authenticate` header carries a `resource_metadata` link to it. ## How a client connects 1. The client calls the resource without a token and gets a `401` with a `resource_metadata` link. 2. It reads the protected resource metadata to find the authorization server. 3. It reads the authorization server metadata to find the endpoints. 4. It registers itself at the `registration_endpoint`. 5. It sends the person to the `authorization_endpoint` with a PKCE challenge. The person approves the requested scopes on Guild's consent screen. 6. It exchanges the returned code at the `token_endpoint`, then sends the access token as a Bearer token. # Exchange an authorization code or refresh token for an access token Source: https://docs.guild.ai/api-reference/oauth/exchange-an-authorization-code-or-refresh-token-for-an-access-token /api-reference/openapi.yaml post /oauth/token # Register an OAuth client Source: https://docs.guild.ai/api-reference/oauth/register-an-oauth-client /api-reference/openapi.yaml post /oauth/register Dynamic client registration ([RFC 7591](https://www.rfc-editor.org/rfc/rfc7591)). An MCP client registers itself before its first authorization request, so nobody has to add it by hand. This endpoint requires no authentication. Every client registered here is public: it holds no secret and proves itself on each authorization with PKCE, so registering grants nothing on its own -- the user's consent is still required. Each `redirect_uri` must use `https`, or `http` on a loopback address, and must not contain a fragment. Registration is rate-limited to 10 requests per hour per IP address. Fields a client sends that are not listed here are ignored. # Start an OAuth authorization by redirecting to the consent page Source: https://docs.guild.ai/api-reference/oauth/start-an-oauth-authorization-by-redirecting-to-the-consent-page /api-reference/openapi.yaml get /oauth/authorize # Get a session Source: https://docs.guild.ai/api-reference/sessions/get-a-session /api-reference/openapi.yaml get /sessions/{session_id} Requires `workspaces:read`. # List session events Source: https://docs.guild.ai/api-reference/sessions/list-session-events /api-reference/openapi.yaml get /sessions/{session_id}/events Requires `workspaces:read` and `agents:read`. Events default to newest-first (`sort_by=-id`) with a limit of 20, so a naive read returns the tail of the conversation in reverse. For polling, pass `from_id` as an exclusive cursor (`id > from_id`) so each poll returns only what happened since the last one -- event ids are UUIDv7 and therefore time-ordered. The agent's reply arrives as a `runtime_done` event whose `content.text` carries the message; events persist when a turn completes, not while the model is streaming, so a poll during generation returns nothing new until the turn finishes. A key missing `agents:read` currently gets a `500`, not a filtered `200` or a `403` -- serializing an agent task reads details the key isn't allowed to see, and that read fails loudly instead of being omitted. Grant `agents:read` alongside `workspaces:read` for any session that ran an agent. # List session tasks Source: https://docs.guild.ai/api-reference/sessions/list-session-tasks /api-reference/openapi.yaml get /sessions/{session_id}/tasks Requires `workspaces:read` and `agents:read` -- see the note on session events above about the `500` when `agents:read` is missing. # List the runtimes a session's tasks ran on Source: https://docs.guild.ai/api-reference/sessions/list-the-runtimes-a-sessions-tasks-ran-on /api-reference/openapi.yaml get /sessions/{session_id}/runtimes Requires `workspaces:read`. # Send a message to a session Source: https://docs.guild.ai/api-reference/sessions/send-a-message-to-a-session /api-reference/openapi.yaml post /sessions/{session_id}/events Requires `sessions:write`. The message is authored by the key itself (`author.type: "api_key"`) -- a key may never author as anyone else. The `agent_id` field is accepted but ignored for a key, so a key cannot switch which agent answers mid-conversation; start a new session instead. A key converses only in the chat sessions it initiated -- posting into any other session (another key's chat, a person's chat, a trigger session) is `404`. # Create a skill version Source: https://docs.guild.ai/api-reference/skills/create-a-skill-version /api-reference/openapi.yaml post /skills/{skill_id_or_name}/versions Requires `skills:write`. # Get a skill Source: https://docs.guild.ai/api-reference/skills/get-a-skill /api-reference/openapi.yaml get /skills/{skill_id_or_name} Requires `skills:read`. # Activate a trigger Source: https://docs.guild.ai/api-reference/triggers/activate-a-trigger /api-reference/openapi.yaml post /triggers/{trigger_id}/activate # Deactivate a trigger Source: https://docs.guild.ai/api-reference/triggers/deactivate-a-trigger /api-reference/openapi.yaml post /triggers/{trigger_id}/deactivate # Get a trigger Source: https://docs.guild.ai/api-reference/triggers/get-a-trigger /api-reference/openapi.yaml get /triggers/{trigger_id} # List the sessions a trigger started Source: https://docs.guild.ai/api-reference/triggers/list-the-sessions-a-trigger-started /api-reference/openapi.yaml get /triggers/{trigger_id}/sessions # Run a scheduled trigger now Source: https://docs.guild.ai/api-reference/triggers/run-a-scheduled-trigger-now /api-reference/openapi.yaml post /triggers/{trigger_id}/run # Update a trigger Source: https://docs.guild.ai/api-reference/triggers/update-a-trigger /api-reference/openapi.yaml patch /triggers/{trigger_id} # Attach a skill to a workspace Source: https://docs.guild.ai/api-reference/workspaces/attach-a-skill-to-a-workspace /api-reference/openapi.yaml post /workspaces/{workspace_id_or_name}/workspace_skills # Create a dedicated API-key credential for a workspace agent Source: https://docs.guild.ai/api-reference/workspaces/create-a-dedicated-api-key-credential-for-a-workspace-agent /api-reference/openapi.yaml post /workspace_agents/{workspace_agent_id}/credentials/api-key The key is stored under the workspace owner's account and used only by this agent. Callable by a user or by an account API key with integrations write scope; a key can only connect credentials to agents it installed itself, under its own account. With ``replace``, every live grant on the agent for the integration that serves every member is revoked in the same transaction, whoever made it. Under per-member resolution a member's grant of their own credential serves only them, so it stays. # Create a session in a workspace Source: https://docs.guild.ai/api-reference/workspaces/create-a-session-in-a-workspace /api-reference/openapi.yaml post /workspaces/{workspace_id_or_name}/sessions Requires `sessions:write` on a workspace the key's account owns. A key may create `chat` and `agent_test` sessions; `api_trigger` is a `403`. The key is recorded as the session's `initiator` (serialized `type: "api_key"`), and a chat's agent begins executing `initial_prompt` immediately. # Create a trigger in a workspace Source: https://docs.guild.ai/api-reference/workspaces/create-a-trigger-in-a-workspace /api-reference/openapi.yaml post /workspaces/{workspace_id_or_name}/triggers Requires `workspaces:write` and `agents:read`. A key may create `time` (schedule) triggers only -- `webhook` and `api` triggers are a `403`. `workspace_agent_id` must name an agent installed in this workspace. The key is recorded as the trigger's creator. See [Schedule triggers](/platform/schedule-triggers). # Create a workspace Source: https://docs.guild.ai/api-reference/workspaces/create-a-workspace /api-reference/openapi.yaml post /workspaces Requires `workspaces:write`. The key is recorded as the workspace's creator; `owner_id` must be the key's own account -- aiming at another account is `403`. # Create a workspace context Source: https://docs.guild.ai/api-reference/workspaces/create-a-workspace-context /api-reference/openapi.yaml post /workspaces/{workspace_id_or_name}/contexts # Detach a skill from a workspace Source: https://docs.guild.ai/api-reference/workspaces/detach-a-skill-from-a-workspace /api-reference/openapi.yaml delete /workspaces/{workspace_id_or_name}/workspace_skills/{workspace_skill_id} # Get a workspace and its compiled context Source: https://docs.guild.ai/api-reference/workspaces/get-a-workspace-and-its-compiled-context /api-reference/openapi.yaml get /workspaces/{workspace_id_or_name} Requires `workspaces:read`. A workspace with restricted membership (`should_restrict_members`) is invisible to every account key regardless of scope, and returns `404`. # Get an installed agent Source: https://docs.guild.ai/api-reference/workspaces/get-an-installed-agent /api-reference/openapi.yaml get /workspace_agents/{workspace_agent_id} # Grant a credential to an installed agent Source: https://docs.guild.ai/api-reference/workspaces/grant-a-credential-to-an-installed-agent /api-reference/openapi.yaml post /workspace_agents/{workspace_agent_id}/credential-associations Requires `integrations:write`. Creating credentials outside this dedicated mint stays human-only by design; the partner flow is admin-connects-once, key-attaches. # Install an agent in a workspace Source: https://docs.guild.ai/api-reference/workspaces/install-an-agent-in-a-workspace /api-reference/openapi.yaml post /workspaces/{workspace_id_or_name}/workspace_agents Requires `workspaces:write`, not `agents:write` -- the workspace-agent CREATE rule delegates to the workspace's own UPDATE privacy. # List a workspace's contexts Source: https://docs.guild.ai/api-reference/workspaces/list-a-workspaces-contexts /api-reference/openapi.yaml get /workspaces/{workspace_id_or_name}/contexts # List a workspace's members Source: https://docs.guild.ai/api-reference/workspaces/list-a-workspaces-members /api-reference/openapi.yaml get /workspaces/{workspace_id_or_name}/memberships # List a workspace's sessions Source: https://docs.guild.ai/api-reference/workspaces/list-a-workspaces-sessions /api-reference/openapi.yaml get /workspaces/{workspace_id_or_name}/sessions Requires `workspaces:read`. # List a workspace's triggers Source: https://docs.guild.ai/api-reference/workspaces/list-a-workspaces-triggers /api-reference/openapi.yaml get /workspaces/{workspace_id_or_name}/triggers # List an installed agent's version upgrades Source: https://docs.guild.ai/api-reference/workspaces/list-an-installed-agents-version-upgrades /api-reference/openapi.yaml get /workspace_agents/{workspace_agent_id}/upgrades # List the agents installed in a workspace Source: https://docs.guild.ai/api-reference/workspaces/list-the-agents-installed-in-a-workspace /api-reference/openapi.yaml get /workspaces/{workspace_id_or_name}/workspace_agents Requires `workspaces:read` and `agents:read`. # List the credentials granted to an installed agent Source: https://docs.guild.ai/api-reference/workspaces/list-the-credentials-granted-to-an-installed-agent /api-reference/openapi.yaml get /workspace_agents/{workspace_agent_id}/credential-associations Requires `workspaces:read`. Returns the credentials shared with the workspace agent, one row per association. # List the current user's workspaces Source: https://docs.guild.ai/api-reference/workspaces/list-the-current-users-workspaces /api-reference/openapi.yaml get /me/workspaces # List the skills attached to a workspace Source: https://docs.guild.ai/api-reference/workspaces/list-the-skills-attached-to-a-workspace /api-reference/openapi.yaml get /workspaces/{workspace_id_or_name}/workspace_skills # Revoke a credential from an installed agent Source: https://docs.guild.ai/api-reference/workspaces/revoke-a-credential-from-an-installed-agent /api-reference/openapi.yaml delete /workspace_agents/{workspace_agent_id}/credential-associations/{association_id} Requires `integrations:write`. Disconnects the credential from this workspace agent; for a credential created just for this agent (rather than an existing one shared with it), deleting the association deletes that credential too. Callable by an account admin, the workspace agent's installer, or the credential's own owner. # Uninstall an agent from a workspace Source: https://docs.guild.ai/api-reference/workspaces/uninstall-an-agent-from-a-workspace /api-reference/openapi.yaml delete /workspace_agents/{workspace_agent_id} # Update an installed agent's version or settings Source: https://docs.guild.ai/api-reference/workspaces/update-an-installed-agents-version-or-settings /api-reference/openapi.yaml patch /workspace_agents/{workspace_agent_id} # guild agent logs Source: https://docs.guild.ai/cli/agent-logs Reference for guild agent logs, which displays the build and validation step logs for a Guild agent version, including TypeScript compiler errors. `guild agent logs` retrieves and displays the build and validation step logs for an agent version. Use it to inspect TypeScript compiler output and other validation details without running a full `guild agent save --wait` cycle. ## Synopsis ```bash theme={null} guild agent logs [identifier] [version-id] ``` ## Arguments | Argument | Description | | - | - | | `[identifier]` | Agent ID or full name (e.g., `owner~agent-name`). If omitted, reads from `guild.json` in the current directory. | | `[version-id]` | ID of the version whose logs to display. If omitted, uses the latest version. | ## Options | Option | Description | | - | - | | `--json` | Output raw JSON instead of formatted text (global flag). | ## Output Each build and validation step is printed with its status. SUCCEEDED displays in green, FAILED and ERRORED in red, RUNNING in yellow, and other statuses in dim text. Log content for each step follows its header line. ```text theme={null} build SUCCEEDED ──────────────────────────────────────────────────────────── validate FAILED src/index.ts(12,5): error TS2345: ... src/index.ts(27,3): error TS7006: ... ``` If the version has no recorded steps, the command prints `No steps found`. ## Errors | Condition | Exit code | Resolution | | - | - | - | | Not authenticated | `1` | Run `guild auth login`. | | Agent or version not found | `1` | Run `guild agent list` or `guild agent versions `. | | Cannot connect to server | `1` | Check your connection and run `guild doctor`. | ## Examples Inspect logs for the latest version of the agent in the current directory: ```bash theme={null} guild agent logs ``` Inspect logs for a specific agent: ```bash theme={null} guild agent logs owner~my-agent ``` Inspect logs for a specific version: ```bash theme={null} guild agent logs owner~my-agent ``` Run `guild agent logs` after a failed `guild agent save --wait` or `guild agent revalidate` to re-inspect step details without triggering a new save. # Commands Source: https://docs.guild.ai/cli/commands Reference for all Guild CLI commands. Every Guild CLI command follows the pattern `guild `. Each command has its own reference page. | Command | Description | | - | - | | [`guild auth`](/cli/commands/auth) | Log in to Guild, log out, and inspect your authentication state. | | [`guild workspace`](/cli/commands/workspace) | Create, select, and manage workspaces, their agents, and their context. | | [`guild agent`](/cli/commands/agent) | Build, test, publish, and manage agents. | | [`guild chat`](/cli/commands/chat) | Chat with The Smith, Guild's built-in support agent. | | [`guild session`](/cli/commands/session) | List and inspect sessions, their events, and their tasks. | | [`guild trigger`](/cli/commands/trigger) | Create and manage triggers that run agents automatically. | | [`guild factory`](/cli/commands/factory) | Set up, start, inspect, and test a Software Factory. | | [`guild integration`](/cli/commands/integration) | Build, version, and test custom integrations. | | [`guild llm`](/cli/commands/llm) | Manage LLM credentials and model policies. | | [`guild skill`](/cli/commands/skill) | Create and manage reusable skill packages. | | [`guild container-image`](/cli/commands/container-image) | Register and manage container images. | | [`guild runtime-environment`](/cli/commands/runtime-environment) | Create, modify, and test runtime environments. | | [`guild api`](/cli/commands/api) | Call any Guild REST API endpoint directly. | | [`guild config`](/cli/commands/config) | Read and write global CLI configuration. | | [`guild doctor`](/cli/commands/doctor) | Diagnose problems with your Guild CLI setup. | | [`guild setup`](/cli/commands/setup) | Install Guild skills for your coding assistant in the current project. | | [`guild version`](/cli/commands/version) | Show the Guild CLI version. | ## Global options These options are accepted by every `guild` command. | Option | Description | | - | - | | `--mode ` | Output format: `interactive` (default), `json`, or `jsonl`. Use `json` or `jsonl` for machine-readable output in scripts and CI pipelines. | | `--debug` | Enable debug mode with verbose logging. | | `--quiet`, `-q` | Suppress progress and log messages, but keep warnings and errors. | | `--non-interactive` | Disable interactive prompts, for CI, scripts, and coding agents. | `--mode` is read from the full command line, so it can go before or after the subcommand, and `--mode=json` works as well as `--mode json`: ```bash theme={null} guild --mode json agent list guild agent list --mode json ``` `--json` is a hidden backward-compatible alias for `--mode json`. It still works but does not appear in `guild --help`. Use `--mode json` in new scripts. ## Event filtering [`guild chat`](/cli/commands/chat), [`guild workspace chat`](/cli/commands/workspace#chat), [`guild agent test`](/cli/commands/agent#test), and [`guild session events`](/cli/commands/session#events) accept `--events ` to choose which session event types to show. The flag requires a value. | Value | Shows | | - | - | | `user` | User-facing events. This is the default. | | `system` | System and debug events only. | | `all` | Both groups. | | `none` | No events. On `guild session events`, `none` applies no filter and lists every event. | | `,` | Only the named types, for example `agent_console,llm_start`. | Whatever you pass replaces the default entirely, so `--events system` hides user-facing events rather than adding to them. **User events**, shown by default: `user_message`, `agent_notification_message`, `agent_notification_progress`, `agent_notification_error`, `container_log`, `credentials_request`, `agent_install_request`, `trigger_message`, `system_error` **System and debug events**, hidden by default: `agent_console`, `runtime_start`, `runtime_running`, `runtime_waiting`, `runtime_error`, `runtime_done`, `llm_start`, `llm_done` These two groups mirror the **Filter by type** modal in the web UI. # guild agent Source: https://docs.guild.ai/cli/commands/agent Reference for guild agent: scaffold, chat with, test, save, publish, fork, and archive Guild agents, and inspect their versions, logs, and tools. Build and manage agents. Each subcommand has its own section below, in alphabetical order. Most commands take an optional agent identifier: an agent ID or a full name such as `myorg~my-agent`. Leave it out to use the agent in `guild.json` in the current directory. A typical development loop looks like this: ```bash theme={null} guild agent init --name my-agent # Scaffold a new agent guild agent chat # Try it with an ephemeral build guild agent test # Run a test session guild agent save --message "First version" # Save a draft version guild agent publish --wait # Validate and publish it ``` ## archive Archive an agent. Archiving removes it from every workspace and stops new runs. See [Disabling an agent](/platform/agents#disabling-an-agent) for what changes. ```bash theme={null} guild agent archive # Archive the agent in the current directory guild agent archive # Archive a specific agent ``` To restore an archived agent, use [`unarchive`](#unarchive). ## capabilities Show an agent's resolved tools, grouped by their source: integrations, sub-agents, and built-in or legacy services. Each tool is marked `read`, `write`, or `unknown`. `unknown` is shown separately from `read` because an unclassified tool may write. ```bash theme={null} guild agent capabilities # Tools for the current directory's agent guild agent capabilities # Tools for a specific agent guild agent capabilities --version # Use a specific version instead of the latest published guild agent capabilities --mode json # Emit the raw JSON payload ``` | Option | Description | | - | - | | `--version ` | The version to inspect. Defaults to the latest published version. | | `--mode json` | Emit the raw payload, with `version_id`, `tools`, and `access` fields. | The command requires authentication, so run `guild auth login` first. Example output: ```text theme={null} Integration: github read github_pulls_get write github_issues_create Sub-agent: guildai/triage-agent unknown run_triage Built-in: ui unknown ui_prompt ``` With `--mode json`: ```json theme={null} { "version_id": "ver_01ABCDEF", "tools": [ ... ], "access": { "github_pulls_get": "read", "github_issues_create": "write", "run_triage": "unknown" } } ``` ## categories List agent categories, or show one category and the tags it allows. ```bash theme={null} guild agent categories # List all categories guild agent categories engineering # Show one category and its allowed tags ``` The list doesn't include tags. To see a category's allowed tags, pass its name. ## chat Chat with the agent you're developing, from inside the agent directory. By default, `guild agent chat` builds an ephemeral version from your local files and starts a new session. Unchanged files reuse the cached build. ```bash theme={null} guild agent chat # Interactive chat using an ephemeral build guild agent chat "Summarize this PR" # Start with an initial prompt guild agent chat --resume # Resume an existing session guild agent chat --mode jsonl # Use JSONL input and output guild agent chat --agent-version # Chat with a specific existing version guild agent chat --no-cache # Force a fresh ephemeral build ``` | Option | Description | | - | - | | `--agent-version ` | Chat with an existing version, given as a UUID or version number, instead of an ephemeral build. | | `--mode ` | Input and output mode: `interactive` (default), `json`, or `jsonl`. | | `--no-cache` | Skip the ephemeral build cache and force a fresh build. | | `--no-splash` | Skip the splash screen animation. | | `--open` | Open the session in the Guild web app. | | `--path ` | The agent directory. Defaults to the current directory. | | `--resume ` | Resume an existing session. Works in every mode. | | `--workspace ` | The workspace to run in, as an ID or full name such as `owner~workspace-name`. | Ephemeral builds include only files tracked by Git. `guild agent chat` and `guild agent test` upload files that are committed or staged with `git add`, and ignore new untracked files until you stage them. Modified tracked files upload their working-tree content, so you can try changes to existing files without committing them. Resuming a session skips version resolution and ephemeral builds, because the session already pins its agent version and workspace. `--workspace` and `--agent-version` are ignored when you resume. In `--mode json` and `--mode jsonl`, resuming appends your input to the session as a new user message. The CLI reports the session's ID, and response polling only considers events created after your message. If the session doesn't exist or you can't access it, `guild agent chat` exits with code `1` without building the agent and prints: ```text theme={null} Cannot resume session '': it does not exist or you do not have access to it. List your sessions with: guild session list ``` ## clone Clone an agent's repository into a local directory. ```bash theme={null} guild agent clone guild agent clone --directory ./my-agent ``` | Option | Description | | - | - | | `--directory ` | The directory to clone into. | | `--force` | Clone even if the directory isn't empty. | ## code Fetch an agent's latest code. By default, it prints the files as JSON and includes only published versions. ```bash theme={null} guild agent code # Latest published code, as JSON guild agent code --draft # Include draft versions guild agent code --output ./src # Write the files to a directory ``` | Option | Description | | - | - | | `--draft` | Include draft versions. | | `--output ` | Write the files to a directory instead of printing JSON. | ## diff Show what changed between your local files and a published version, as a colored unified diff. ```bash theme={null} guild agent diff # Compare against the latest published version guild agent diff 1.0.4 # Compare against a specific version ``` Run it from inside an agent directory. The command needs a `guild.json`, and compares the Git-tracked files in your working tree, the same set `test` and `chat` upload. ## fork Fork a published agent version into a new, independent agent with its own repository. ```bash theme={null} guild agent fork # Fork the latest published version guild agent fork : # Fork a specific version guild agent fork --name my-fork # Name the forked agent guild agent fork --owner # Assign it to an owner guild agent fork --directory ./my-fork # Clone into a specific directory guild agent fork --category # Change the fork's category guild agent fork --tags a,b # Set tags on the fork ``` | Option | Description | | - | - | | `--category ` | The fork's category. Defaults to the source agent's category. | | `--description ` | A description for the fork. | | `--directory ` | The directory to clone the fork into. | | `--name ` | A name for the fork. | | `--owner ` | The owner, by name or ID. | | `--tags ` | Comma-separated tags for the fork. | A fork inherits the source agent's category and its tags, except Guild's own `guild:`-prefixed tags. Pass `--category` to change the category. The source tags are then dropped, and any `--tags` you pass are checked against the new category's allowed tags. Run [`guild agent categories `](#categories) to see them. ## get Show an agent's details. ```bash theme={null} guild agent get # The agent in the current directory guild agent get # A specific agent ``` ## grep Search agent files for lines that match a pattern. The pattern is a JavaScript regular expression. ```bash theme={null} guild agent grep "task\.llm" # Search the current agent guild agent grep "task\.llm" --all # Search all agents you can see guild agent grep "task\.llm" --all --published # Search only published agents ``` | Option | Description | | - | - | | `--all` | Search all agents, not just the current one. | | `--published` | Search only published agents. Requires `--all`. | ## init Initialize a new agent, in a new directory or the current one. ```bash theme={null} guild agent init guild agent init --name my-agent guild agent init --name my-agent --template LLM guild agent init --name my-agent --agent-type GUILD_NATIVE guild agent init --fork # Start from an existing agent guild agent init --owner # Specify the owner by name or ID guild agent init --name my-agent --category development --tags "code-review,testing" ``` | Option | Description | | - | - | | `--agent-type ` | The agent type. See the table below. | | `--category ` | The agent's category. Run [`guild agent categories`](#categories) to list them. | | `--directory ` | The directory to initialize. Defaults to `./`, created if needed. | | `--force` | Overwrite an existing `guild.json`. | | `--fork ` | Start from an existing agent. | | `--name ` | The agent's name. | | `--owner ` | The owner, by name or ID. | | `--tags ` | Comma-separated tags, from the category's allowed tags. | | `--template