Agent

Field	Type	Behavior	Description
`name`	string	OUTPUT_ONLY	Resource name (`agents/{id}`)
`title`	string		Human-readable title for the agent
`description`	string		Description of what this agent does
`prompt`	string		Initial prompt used to start agent sessions
`connections`	AgentConnection[]		Connections and their enabled tools for this agent
`mcp_connections`	MCPConnection[]		MCP server connections enabled for this agent. Only listed connections are loaded at runtime.
`skills`	Skill[]	OUTPUT_ONLY	Skills available to this agent’s fireshell sessions. Populated by the server from the skills bucket on every `GetAgent` call; source of truth is the `name` / `description` user-metadata stamped on each `SKILL.md` object at deploy time.
`state`	AgentState		The operational state of the agent
`tags`	string[]		Tags assigned to this agent (`tags/{tag_id}`). Cannot include system tags.
`network_profile`	string		Network profile whose allow-list gates this agent’s fireshell egress (`network-profiles/{id}`). When unset, resolves to `network-profiles/default` at runtime. See Network Profiles.
`plan_session`	string		The session that planned this agent, if created by an agent session (`agents/{agent}/sessions/{session}`)
`system`	boolean	OUTPUT_ONLY	Whether this is a system agent (auto-created, not user-managed)
`created_by`	string	OUTPUT_ONLY	The ID of the user who created this agent
`create_time`	timestamp	OUTPUT_ONLY	When the agent was created
`update_time`	timestamp	OUTPUT_ONLY	When the agent was last modified
`delete_time`	timestamp	OUTPUT_ONLY	When the agent was soft-deleted (null if active)
`expire_time`	timestamp		Optional expiration time. After this time, the agent will be automatically archived.

Example

{
  "name": "agents/error-rate-monitor",
  "title": "Error Rate Monitor",
  "description": "Monitors services for abnormal error rates and escalation patterns.",
  "prompt": "You are a monitoring agent for production services. Your job is to detect abnormal errors...",
  "connections": [
    {
      "name": "connections/prod-postgres",
      "enabledTools": ["TOOL_POSTGRES_QUERY"]
    },
    {
      "name": "connections/prod-prometheus",
      "enabledTools": ["TOOL_PROMQL_QUERY", "TOOL_PROMQL_QUERY_RANGE"]
    }
  ],
  "mcpConnections": [
    {
      "name": "mcp-connections/internal-tools"
    }
  ],
  "tags": ["tags/production", "tags/monitoring"],
  "state": "AGENT_STATE_ON",
  "system": false,
  "skills": [
    {"name": "querying-postgres", "description": "Query a Postgres database using psql and discover schemas before writing real queries."},
    {"name": "querying-prometheus-metrics", "description": "Resolve label/metric names via metadata tools before writing PromQL; bound windows; prefer rate/increase on counters."}
  ],
  "createTime": "2026-02-21T20:37:33.623697Z",
  "updateTime": "2026-02-21T20:40:06.610686Z"
}

Agent State

Value	Description
`AGENT_STATE_UNSPECIFIED`	Default value, not used
`AGENT_STATE_ON`	Agent is active and running
`AGENT_STATE_OFF`	Agent is disabled
`AGENT_STATE_REVIEW_REQUIRED`	Agent requires human review before activation
`AGENT_STATE_RECOMMENDED`	Agent is recommended but not yet activated

Agent Connection

Field	Type	Description
`name`	string	Resource name of the connection (`connections/{connection}`)
`enabled_tools`	Tool[]	List of tools enabled for this agent from this connection. If empty, all tools configured on the connection are enabled.

MCP Connection

Field	Type	Description
`name`	string	Resource name of the MCP connection (`mcp-connections/{mcp_connection}`)
`server_url`	string	REQUIRED. URL of the external MCP server. Both `http://` and `https://` are supported, over a network transport or directly.
`network_transport`	string	Optional. Resource name of a NetworkTransport (`network-transports/{network_transport}`) to route this connection through when the MCP server is reachable only over a private overlay network (e.g. a Tailscale tailnet). Leave empty to connect over the public internet. Settable on the direct-create auth modes (`bearer_token` and `no_auth`); OAuth connections connect over the public internet.
`bearer_token`	BearerTokenConfig	API token / PAT auth (oneof `auth`). Create directly via `CreateMCPConnection`.
`dynamic_oauth`	DynamicOAuthConfig	OAuth with dynamic client registration, RFC 7591 (oneof `auth`). Created via `InitiateDynamicOAuth`.
`static_oauth`	StaticOAuthConfig	OAuth with a pre-registered client ID/secret (oneof `auth`). Created via `InitiateStaticOAuth`.
`no_auth`	NoAuthConfig	No authentication — no credentials are sent (oneof `auth`). For internal/localhost servers that require no auth. Create directly via `CreateMCPConnection`.
`refresh_status`	google.rpc.Status	OUTPUT_ONLY. Last refresh error from the credential-refresh cron or request-path refresh, if any. Cleared on a successful refresh. When the carried `ErrorInfo.reason` is `CONNECTION_FAILURE` (e.g. revoked refresh token), the cron skips this row to avoid retrying a permanently-invalid token. Transient reasons (`INTERNAL_ERROR`) do not suppress retries.

Authentication is configured via the auth oneof — set exactly one of bearer_token, dynamic_oauth, static_oauth, or no_auth. CreateMCPConnection accepts the credential-free modes (bearer_token and no_auth); the OAuth modes are established through the InitiateDynamicOAuth / InitiateStaticOAuth flows.

Bearer Token Config

Field	Type	Behavior	Description
`token`	string	INPUT_ONLY	API token or personal access token sent as `Authorization: Bearer <token>`.

No Auth Config

Empty message. Selecting no_auth makes the connection send no Authorization header — for MCP servers that require no authentication (e.g. internal or localhost servers, often combined with a network_transport).

Skill

A piece of per-connection / per-subsystem documentation mounted read-only into the agent’s fireshell chamber under /run/skills/. One Skill corresponds to one SKILL.md file on the deployment’s skills bucket. The list is returned as an OUTPUT_ONLY field on Agent — clients read it but do not set it.

Field	Type	Description
`name`	string	Short name (matches the `SKILL.md` frontmatter `name:`). Also the skill’s directory slug under `/run/skills/`; callers that need the in-chamber file path construct it as `/run/skills/<name>/SKILL.md`.
`description`	string	One-line description (matches the `SKILL.md` frontmatter `description:`).