Send one message to a run: a course correction to a live run without stopping the work, or, when the run has finished and its workspace is retained, a follow-up that continues the SAME run and save...
Upload a file into the messaging-channel thread a run reports to — a demo recording, for example — so it renders natively there (Slack plays video uploads inline).
The agent to do the work. Omit when calling through an MCP gateway to select an assigned runtime subagent using the gateway's load-balancing policy.
exclude_agent_ids
string[]
No
Runtime subagents that already failed on a previous attempt for this request, to skip when selecting a fallback on an MCP gateway.
credential_grant_ids
string[]
No
One-time credential_grant_id handles minted by transfer_credential({ ephemeral: true }). Consumed at launch and bound only to the winning runtime pod.
message
string
Yes
What the agent should do, including handoff context and acceptance criteria.
attachments
object[]
No
Input files staged before the first turn. For repository work, include a patch for uncommitted changes and identify the base commit in message. Never include credentials.
attachments[].name
string
Yes
attachments[].contentType
string
Yes
attachments[].contentBase64
string
Yes
limits
object
No
Limits for this run, each at or below the Agent's own (for the tier, its largest tier); a larger value is refused with the maximum named. Omit to take the Agent's defaults.
limits.tier
string
No
The name of one of the organization's runtime tiers, at or below this Agent's scaleup tier. Choose by size, not by name: inside a run, $ARCHESTRA_AGENT_RUNTIME_TIERS lists the tiers the run may move to with their CPU, memory and workspace size; pick the smallest that covers the work. To move work to another tier, start a run of the same Agent at that tier and hand over the branch. A tier above the scaleup tier is refused with the allowed tiers and their sizes named.
limits.min_cpu
number
No
CPUs the work needs. The run gets the smallest tier this Agent may use with at least this many and no smaller workspace than the Agent's default tier; refused with the allowed tiers named when none has. Use this when the tier names are unknown.
limits.min_memory_gib
number
No
GiB of memory the work needs, with the same effect as min_cpu.
limits.idle_timeout_minutes
integer
No
limits.max_duration_hours
integer
No
Hours until the run and its saved files end. Keep it short for work that nobody continues.
limits.max_cost_usd
integer
No
Output
Field
Type
Required
Description
run
object
Yes
run.run_id
string
Yes
Stable handle for every follow-up: get_agent_run, steer_agent_run, cancel_agent_run and the workspace file tools.
With state=failed, include failed earlier turns since this UTC timestamp, ordered by failure time. Keeps the same Agent access checks and limit; cannot be combined with mine_only.
current_thread_only
boolean
No
Only runs originating in the current messaging thread. Requires messaging context; never falls back to an unfiltered list.
limit
integer
No
Output
Field
Type
Required
Description
runs
object[]
Yes
runs[].run_id
string
Yes
Stable handle for every follow-up: get_agent_run, steer_agent_run, cancel_agent_run and the workspace file tools.
Display name of the agent doing the work, when known.
runs[].status_reason
string | null
Yes
Why the run is in its state, when there is something to say.
runs[].failure
object | null
Yes
Machine-readable failure of a failed run: a stable code and whether a new run of the same Agent is likely to succeed unchanged. Null otherwise.
runs[].created_at
string
No
ISO 8601.
runs[].state_changed_at
string | string | null
Yes
ISO 8601 of the last transition.
runs[].llm_session_id
string | null
No
Verified LLM telemetry session key for /llm/logs/:id (the run's workload name); URL-encode it as one path segment. Null when no readable logged session is available. It is not a run_id: never pass it to the run tools.
runs[].title
string
No
runs[].prompt
string
No
runs[].started_at
string
No
runs[].ended_at
string | null
No
runs[].hard_deadline_at
string
No
When the runtime will be forcefully stopped.
runs[].last_model_activity_at
string | null
No
Most recent model request attributed to this run.
runs[].attention_state
"input_required" | "auth_required" | null
No
Native runtime signal that the live process needs user attention.
The Agent to give the credential to. Omit when calling through an MCP gateway to transfer the credential to all runtime subagents assigned to the gateway.
environment
object[]
Yes
Exactly one credential to transfer. Never include more than the task needs.
environment[].key
string
Yes
Environment variable name, e.g. AWS_SECRET_ACCESS_KEY.
environment[].type
"secret"
Yes
Always 'secret'. Marks the value for redaction in logs.
environment[].value
string
No
The credential value to transfer. OMIT IT to declare the credential without a value and get back a link the person opens to paste it themselves — the value then never enters your context. Send a value only when the person asked you to move one you already hold.
label
string
No
Human-readable name shown in the Agent's credential list. Defaults to the key.
ephemeral
boolean
No
When true, mints a short-lived one-time credential_grant_id handle instead of persisting the secret in the database or mutating subagent declarations. Pass the returned credential_grant_id to start_agent_run so the secret is bound only to the single winning subagent pod.
ttl_seconds
integer
No
Optional TTL in seconds (30–3600, default 300) for an ephemeral credential grant. Implies ephemeral: true.
Output
Field
Type
Required
Description
key
string
Yes
The environment variable the value is stored under.
scope
"personal"
Yes
Who the value applies to. Always personal to the calling user.
declarationCreated
boolean
Yes
Whether this call declared the credential on the Agent.
valueStored
boolean
Yes
Whether a value is now stored. False means the credential is declared and still empty.
url
string | null
Yes
Where the person pastes the value. Null when this call already stored one.
urls
string[]
No
All per-subagent setup links when declaring a credential across multiple subagents.
ephemeral
boolean
No
True when the credential was minted as a short-lived one-time grant instead of stored in the database.
credential_grant_id
string | null
No
One-time credential grant handle to pass to start_agent_run when ephemeral is true.
expires_in_seconds
integer
No
Seconds until the ephemeral credential grant expires.
availability
string
Yes
When a run can read the value, in plain words.
next_step
string
No
What to do with url: hand it over in the reply text, never inside a question form. Only set while a value is still missing.
Create a new agent with the specified name, optional description, labels, prompts, icon emoji, model, explicit tool assignments, and sub-agent delegations.
Optional key-value labels for organization and categorization.
labels[].key
string
Yes
labels[].value
string
Yes
toolExposureMode
"full" | "search_and_run_only"
No
How tools should be loaded for MCP clients and models. Use 'search_and_run_only' to keep the initial tool list small while letting search_tools find assigned tools and run_tool execute them. MCP gateways defer skill, file, sandbox, run lifecycle and policy-management capabilities in this mode; questions and guardrails session/peer-message controls remain directly available. search_tools summarizes the caller's available built-in capability groups as well as connected MCP servers. Manual gateways also keep explicitly assigned MCP App UI tools available for client rendering. Internal chat keeps assigned skill discovery/loading, file, sandbox and run lifecycle tools directly available for its skill activation and file guidance. App tools (scaffold_app, edit_app, read_app, render_app, list_apps, and the rest of the app surface) are reached through search_tools/run_tool in 'search_and_run_only' mode.
accessAllTools
boolean
No
Allow dynamic tool access: search_tools/run_tool may discover and run any tool the calling user can access (MCP catalog tools and knowledge sources) without assigning it to the agent. Enabling this forces toolExposureMode to 'search_and_run_only', since dynamic access only works through the search/run dispatch surface. Defaults to false. Also gated by the organization's security settings.
accessAllSubagents
boolean
No
Allow dynamic subagent delegation: the agent may delegate to any internal agent the calling user can access, beyond explicitly-configured delegation targets (minus subagent exclusions). Defaults to false.
description
string | null
No
Optional human-readable description of the agent.
icon
string | null
No
Optional emoji icon for the agent.
knowledgeBaseIds
string[]
No
Knowledge base IDs to assign to the agent. Use get_knowledge_bases first when you need to look up IDs by name.
connectorIds
string[]
No
Knowledge connector IDs to assign directly to the agent. Use get_knowledge_connectors first when you need to look up IDs by name.
subAgentIds
string[]
No
Agent IDs to delegate to from this newly created agent.
suggestedPrompts
object[]
No
Optional suggested prompts that appear in the chat UI.
suggestedPrompts[].summaryTitle
string
Yes
Short title shown to users for this suggested prompt.
suggestedPrompts[].prompt
string
Yes
Suggested prompt text users can click to start a conversation.
systemPrompt
string | null
No
The system prompt that defines the agent's behavior.
toolAssignments
object[]
No
Explicit tool assignments to create immediately after the agent is created.
toolAssignments[].toolId
string
Yes
The ID of the tool to assign to the agent.
toolAssignments[].resolveAtCallTime
boolean
No
When true, resolve credentials and execution target at tool call time. Prefer this for builder flows.
toolAssignments[].credentialResolutionMode
"static" | "dynamic" | "enterprise_managed"
No
toolAssignments[].mcpServerId
string | null
No
Optional MCP server installation to pin the tool to when using static credential resolution.
runtime
object
No
Run this agent in its own container (Agent Runtime) instead of the built-in chat harness. Pass { template } for a maintained CLI, or { image } for a custom image. Other fields override the defaults: claudeCode.authentication is 'subscription' (each user signs in with their own Claude account, the default) or 'provider' (bill through llmApiKeyId/modelId); credentials declares environment variables a run needs (users supply values later, or use transfer_credential); ttlHours, idleTimeoutMinutes, and maxCostUsd bound each run; privileged requires an agent administrator.
Maintained CLI to run: 'claude-code' (Claude Code), 'codex' (Codex), 'opencode' (OpenCode), 'hermes' (Hermes), 'openclaw' (OpenClaw), 'grok' (Grok Build), 'kimi' (Kimi Code), 'copilot' (GitHub Copilot CLI). The image, launch command, and model protocol come from the template.
runtime.image
string
No
runtime.command
string[] | null
No
runtime.inferenceProtocol
"openai_responses" | "openai_chat" | "anthropic"
No
networkPolicy
object
No
The agent's own outbound network policy for its Agent Runtime and code sandbox. It replaces the policy of the agent's environment. Requires permission to update environments.
networkPolicy.egressMode
"off" | "restricted" | "unrestricted"
Yes
unrestricted allows all outbound traffic, restricted allows only the listed destinations, off blocks all outbound traffic.
Filter by a configured provider key, or organization-default for agents with no pinned key or model.
limit
integer
No
Maximum number of agents to return.
name
string
No
Optional agent name filter. Use this when the user names an agent but you still need to look up the ID.
access
string[]
No
Only return items the caller reaches in one of these ways: mine (created by the caller), shared (shared with the caller or one of their teams), org (shared with the whole organization), others (not shared with the caller; visible only through admin access). Omit for everything the caller can read. Use ["mine"] for "my agents".
shared_with
string[]
No
Only return items whose own permissions grant read to one of these subjects: org (the whole organization), role:, team:, user:, serviceAccount:. Omit for no filtering.
owner_ids
string[]
No
Only return items created by one of these user IDs. Omit for no filtering.
Output
Field
Type
Required
Description
total
number
Yes
The total number of matching agents.
hint
string
Yes
Says that each agent's tools are that agent's own, not tools you can call.
agents
object[]
Yes
agents[].id
string
Yes
The agent ID.
agents[].name
string
Yes
The agent name.
agents[].scope
"personal" | "team" | "org"
Yes
The agent scope.
agents[].executionMode
"runtime" | "foreground"
Yes
Runtime agents retain a workspace and support steering; foreground agents do not.
agents[].description
string | null
Yes
The agent description, if any.
agents[].resolvedLlmProviderKeyName
string | null
Yes
The configured provider-key name, or null when unconfigured.
agents[].resolvedLlmModelName
string | null
Yes
The configured model name, or null when unconfigured.
agents[].teams
object[]
Yes
Teams attached to it.
agents[].teams[].id
string
Yes
The team ID.
agents[].teams[].name
string
Yes
The team name.
agents[].labels
object[]
Yes
Assigned labels.
agents[].labels[].key
string
Yes
The label key.
agents[].labels[].value
string
Yes
The label value.
agents[].tools
object[]
Yes
agents[].tools[].name
string
Yes
The tool name.
agents[].tools[].description
string | null
Yes
The tool description, if any.
agents[].knowledgeSources
object[]
Yes
Assigned knowledge bases and connectors.
agents[].knowledgeSources[].name
string
Yes
The knowledge source name.
agents[].knowledgeSources[].description
string | null
Yes
The knowledge source description, if any.
agents[].knowledgeSources[].type
"knowledge_base" | "knowledge_connector"
Yes
Whether this source is a knowledge base or connector.
edit_agent
Required RBAC permission: update on the agent (granted per item)
Input
Parameter
Type
Required
Description
id
string
Yes
The ID of the agent to edit. Use get_agent or list_agents to look it up by name.
subAgentIds
string[]
No
Agent IDs to add as delegation targets.
toolAssignments
object[]
No
Explicit tool assignments to add or update on the agent.
toolAssignments[].toolId
string
Yes
The ID of the tool to assign to the agent.
toolAssignments[].resolveAtCallTime
boolean
No
When true, resolve credentials and execution target at tool call time. Prefer this for builder flows.
toolAssignments[].credentialResolutionMode
"static" | "dynamic" | "enterprise_managed"
No
toolAssignments[].mcpServerId
string | null
No
Optional MCP server installation to pin the tool to when using static credential resolution.
description
string | null
No
New description for the agent.
icon
string | null
No
New emoji icon for the agent.
knowledgeBaseIds
string[]
No
Replace the agent's assigned knowledge bases with this set.
labels
object[]
No
Replace the agent's labels with this set.
labels[].key
string
Yes
labels[].value
string
Yes
name
string
No
New name for the agent.
connectorIds
string[]
No
Replace the agent's directly assigned knowledge connectors with this set.
toolExposureMode
"full" | "search_and_run_only"
No
How tools should be loaded for MCP clients and models.
accessAllTools
boolean
No
Allow dynamic tool access: search_tools/run_tool may discover and run any tool the calling user can access without assigning it to the agent. Enabling this forces toolExposureMode to 'search_and_run_only'.
accessAllSubagents
boolean
No
Allow dynamic subagent delegation: the agent may delegate to any internal agent the calling user can access, beyond explicitly-configured delegation targets (minus subagent exclusions).
suggestedPrompts
object[]
No
Replace the agent's suggested prompts.
suggestedPrompts[].summaryTitle
string
Yes
Short title shown to users for this suggested prompt.
suggestedPrompts[].prompt
string
Yes
Suggested prompt text users can click to start a conversation.
systemPrompt
string | null
No
New system prompt for the agent.
runtime
object | null
No
Run this agent in its own container (Agent Runtime) instead of the built-in chat harness. Pass { template } for a maintained CLI, or { image } for a custom image. Other fields override the defaults: claudeCode.authentication is 'subscription' (each user signs in with their own Claude account, the default) or 'provider' (bill through llmApiKeyId/modelId); credentials declares environment variables a run needs (users supply values later, or use transfer_credential); ttlHours, idleTimeoutMinutes, and maxCostUsd bound each run; privileged requires an agent administrator. Replaces the whole runtime: pass every field to keep. Pass null to return the agent to the built-in chat harness.
networkPolicy
object | null
No
The agent's own outbound network policy for its Agent Runtime and code sandbox. It replaces the policy of the agent's environment. Requires permission to update environments. Replaces the whole policy. Pass null to inherit the environment's policy again.
networkPolicy.egressMode
"off" | "restricted" | "unrestricted"
Yes
unrestricted allows all outbound traffic, restricted allows only the listed destinations, off blocks all outbound traffic.
Restricted mode only: a built-in domain allowlist to add (none, common_dependencies, package_managers).
networkPolicy.allowedDomains
string[]
No
Restricted mode only: extra allowed domains, e.g. api.github.com or *.example.com.
networkPolicy.allowedCidrs
string[]
No
Allowed IP ranges in CIDR notation, e.g. 10.0.0.0/8.
llmApiKeyId
string | null
No
Provider API key the agent uses. Set together with modelId. Use list_llm_models to find both. Pass null for both to use the default model.
modelId
string | null
No
Model the agent uses: the model's id from list_llm_models, not its provider name. Set together with llmApiKeyId. Pass null for both to use the default model.
Additional access requirement: Also requires skill:read. Returns an internal agent's skill activation policy.
Input
Parameter
Type
Required
Description
id
string
Yes
The ID of the internal agent.
Output
Field
Type
Required
Description
mode
"all" | "manual"
Yes
revision
integer
Yes
allowedReferences
object[]
Yes
allowedReferences[].source
"native" | "external_mcp" | "plugin"
Yes
"native": A skill-library skill. "external_mcp": A skill from an MCP server. "plugin": A skill bundled in a plugin.
allowedReferences[].skillId
string
When source="native"
The skill-library skill ID.
allowedReferences[].mcpServerId
string
When source="external_mcp"
The MCP server installation ID.
allowedReferences[].uri
string
When source="external_mcp"
The skill resource URI.
allowedReferences[].pluginId
string
When source="plugin"
The plugin ID.
allowedReferences[].skillPath
string
When source="plugin"
The skill root inside the plugin.
excludedReferences
object[]
Yes
excludedReferences[].source
"native" | "external_mcp" | "plugin"
Yes
"native": A skill-library skill. "external_mcp": A skill from an MCP server. "plugin": A skill bundled in a plugin.
excludedReferences[].skillId
string
When source="native"
The skill-library skill ID.
excludedReferences[].mcpServerId
string
When source="external_mcp"
The MCP server installation ID.
excludedReferences[].uri
string
When source="external_mcp"
The skill resource URI.
excludedReferences[].pluginId
string
When source="plugin"
The plugin ID.
excludedReferences[].skillPath
string
When source="plugin"
The skill root inside the plugin.
allowedSkills
object[]
Yes
allowedSkills[].reference
object
Yes
Stable source identity: native uses skillId, external_mcp uses mcpServerId and uri, and plugin uses pluginId and skillPath.
allowedSkills[].reference.source
"native" | "external_mcp" | "plugin"
Yes
"native": A skill-library skill. "external_mcp": A skill from an MCP server. "plugin": A skill bundled in a plugin.
allowedSkills[].reference.skillId
string
When source="native"
The skill-library skill ID.
allowedSkills[].reference.mcpServerId
string
When source="external_mcp"
The MCP server installation ID.
allowedSkills[].reference.uri
string
When source="external_mcp"
The skill resource URI.
allowedSkills[].reference.pluginId
string
When source="plugin"
The plugin ID.
allowedSkills[].reference.skillPath
string
When source="plugin"
The skill root inside the plugin.
allowedSkills[].name
string
Yes
The declared, human-facing skill name.
allowedSkills[].activationName
string
Yes
The exact name to pass to load_skill.
allowedSkills[].description
string
Yes
The skill description.
allowedSkills[].scope
"personal" | "team" | "org"
Yes
The visibility scope through which the skill is shared.
allowedSkills[].providerName
string | null
Yes
Plugin or MCP server name; null for a skill-library entry.
excludedSkills
object[]
Yes
excludedSkills[].reference
object
Yes
Stable source identity: native uses skillId, external_mcp uses mcpServerId and uri, and plugin uses pluginId and skillPath.
excludedSkills[].reference.source
"native" | "external_mcp" | "plugin"
Yes
"native": A skill-library skill. "external_mcp": A skill from an MCP server. "plugin": A skill bundled in a plugin.
excludedSkills[].reference.skillId
string
When source="native"
The skill-library skill ID.
excludedSkills[].reference.mcpServerId
string
When source="external_mcp"
The MCP server installation ID.
excludedSkills[].reference.uri
string
When source="external_mcp"
The skill resource URI.
excludedSkills[].reference.pluginId
string
When source="plugin"
The plugin ID.
excludedSkills[].reference.skillPath
string
When source="plugin"
The skill root inside the plugin.
excludedSkills[].name
string
Yes
The declared, human-facing skill name.
excludedSkills[].activationName
string
Yes
The exact name to pass to load_skill.
excludedSkills[].description
string
Yes
The skill description.
excludedSkills[].scope
"personal" | "team" | "org"
Yes
The visibility scope through which the skill is shared.
excludedSkills[].providerName
string | null
Yes
Plugin or MCP server name; null for a skill-library entry.
hiddenAllowedCount
integer
Yes
hiddenExcludedCount
integer
Yes
patch_agent_skill_policy
Required RBAC permission: update on the agent (granted per item)
Additional access requirement: Also requires skill:read. Requires the current revision and an update grant on the agent. Only skills the caller can access may be added.
Input
Parameter
Type
Required
Description
id
string
Yes
The ID of the internal agent.
patch
object
Yes
The policy changes, guarded by the revision returned by get_agent_skill_policy.
patch.expectedRevision
integer
Yes
patch.mode
"all" | "manual"
No
patch.operations
object[]
No
patch.operations[].op
"add" | "remove"
Yes
patch.operations[].disposition
"allow" | "exclude"
Yes
patch.operations[].reference
object
Yes
Stable source identity: native uses skillId, external_mcp uses mcpServerId and uri, and plugin uses pluginId and skillPath.
patch.operations[].reference.source
"native" | "external_mcp" | "plugin"
Yes
"native": A skill-library skill. "external_mcp": A skill from an MCP server. "plugin": A skill bundled in a plugin.
patch.operations[].reference.skillId
string
When source="native"
The skill-library skill ID.
patch.operations[].reference.mcpServerId
string
When source="external_mcp"
The MCP server installation ID.
patch.operations[].reference.uri
string
When source="external_mcp"
The skill resource URI.
patch.operations[].reference.pluginId
string
When source="plugin"
The plugin ID.
patch.operations[].reference.skillPath
string
When source="plugin"
The skill root inside the plugin.
patch.discardUnavailable
string[]
No
Output
Field
Type
Required
Description
mode
"all" | "manual"
Yes
revision
integer
Yes
allowedReferences
object[]
Yes
allowedReferences[].source
"native" | "external_mcp" | "plugin"
Yes
"native": A skill-library skill. "external_mcp": A skill from an MCP server. "plugin": A skill bundled in a plugin.
allowedReferences[].skillId
string
When source="native"
The skill-library skill ID.
allowedReferences[].mcpServerId
string
When source="external_mcp"
The MCP server installation ID.
allowedReferences[].uri
string
When source="external_mcp"
The skill resource URI.
allowedReferences[].pluginId
string
When source="plugin"
The plugin ID.
allowedReferences[].skillPath
string
When source="plugin"
The skill root inside the plugin.
excludedReferences
object[]
Yes
excludedReferences[].source
"native" | "external_mcp" | "plugin"
Yes
"native": A skill-library skill. "external_mcp": A skill from an MCP server. "plugin": A skill bundled in a plugin.
excludedReferences[].skillId
string
When source="native"
The skill-library skill ID.
excludedReferences[].mcpServerId
string
When source="external_mcp"
The MCP server installation ID.
excludedReferences[].uri
string
When source="external_mcp"
The skill resource URI.
excludedReferences[].pluginId
string
When source="plugin"
The plugin ID.
excludedReferences[].skillPath
string
When source="plugin"
The skill root inside the plugin.
allowedSkills
object[]
Yes
allowedSkills[].reference
object
Yes
Stable source identity: native uses skillId, external_mcp uses mcpServerId and uri, and plugin uses pluginId and skillPath.
allowedSkills[].reference.source
"native" | "external_mcp" | "plugin"
Yes
"native": A skill-library skill. "external_mcp": A skill from an MCP server. "plugin": A skill bundled in a plugin.
allowedSkills[].reference.skillId
string
When source="native"
The skill-library skill ID.
allowedSkills[].reference.mcpServerId
string
When source="external_mcp"
The MCP server installation ID.
allowedSkills[].reference.uri
string
When source="external_mcp"
The skill resource URI.
allowedSkills[].reference.pluginId
string
When source="plugin"
The plugin ID.
allowedSkills[].reference.skillPath
string
When source="plugin"
The skill root inside the plugin.
allowedSkills[].name
string
Yes
The declared, human-facing skill name.
allowedSkills[].activationName
string
Yes
The exact name to pass to load_skill.
allowedSkills[].description
string
Yes
The skill description.
allowedSkills[].scope
"personal" | "team" | "org"
Yes
The visibility scope through which the skill is shared.
allowedSkills[].providerName
string | null
Yes
Plugin or MCP server name; null for a skill-library entry.
excludedSkills
object[]
Yes
excludedSkills[].reference
object
Yes
Stable source identity: native uses skillId, external_mcp uses mcpServerId and uri, and plugin uses pluginId and skillPath.
excludedSkills[].reference.source
"native" | "external_mcp" | "plugin"
Yes
"native": A skill-library skill. "external_mcp": A skill from an MCP server. "plugin": A skill bundled in a plugin.
excludedSkills[].reference.skillId
string
When source="native"
The skill-library skill ID.
excludedSkills[].reference.mcpServerId
string
When source="external_mcp"
The MCP server installation ID.
excludedSkills[].reference.uri
string
When source="external_mcp"
The skill resource URI.
excludedSkills[].reference.pluginId
string
When source="plugin"
The plugin ID.
excludedSkills[].reference.skillPath
string
When source="plugin"
The skill root inside the plugin.
excludedSkills[].name
string
Yes
The declared, human-facing skill name.
excludedSkills[].activationName
string
Yes
The exact name to pass to load_skill.
excludedSkills[].description
string
Yes
The skill description.
excludedSkills[].scope
"personal" | "team" | "org"
Yes
The visibility scope through which the skill is shared.
excludedSkills[].providerName
string | null
Yes
Plugin or MCP server name; null for a skill-library entry.
Availability: Served only when the code runtime is enabled (the same prerequisite as the Code Sandbox tools), because a hook executes in the conversation sandbox.
The script file name (.py or .sh); also the execution-order key within an event.
hooks[].content
string
Yes
The script content.
hooks[].requirements
string[]
Yes
Python dependencies installed before a .py hook runs.
hooks[].enabled
boolean
Yes
Whether the hook currently fires.
hooks[].createdAt
string
Yes
ISO timestamp when the hook was created.
hooks[].updatedAt
string
Yes
ISO timestamp when the hook was last updated.
create_hook
Required RBAC permission: update on the agent (granted per item)
Availability: Served only when the code runtime is enabled (the same prerequisite as the Code Sandbox tools), because a hook executes in the conversation sandbox.
The script file name (.py or .sh); also the execution-order key within an event.
hook.content
string
Yes
The script content.
hook.requirements
string[]
Yes
Python dependencies installed before a .py hook runs.
hook.enabled
boolean
Yes
Whether the hook currently fires.
hook.createdAt
string
Yes
ISO timestamp when the hook was created.
hook.updatedAt
string
Yes
ISO timestamp when the hook was last updated.
update_hook
Required RBAC permission: update on the agent (granted per item)
Availability: Served only when the code runtime is enabled (the same prerequisite as the Code Sandbox tools), because a hook executes in the conversation sandbox.
The script file name (.py or .sh); also the execution-order key within an event.
hook.content
string
Yes
The script content.
hook.requirements
string[]
Yes
Python dependencies installed before a .py hook runs.
hook.enabled
boolean
Yes
Whether the hook currently fires.
hook.createdAt
string
Yes
ISO timestamp when the hook was created.
hook.updatedAt
string
Yes
ISO timestamp when the hook was last updated.
delete_hook
Required RBAC permission: update on the agent (granted per item)
Availability: Served only when the code runtime is enabled (the same prerequisite as the Code Sandbox tools), because a hook executes in the conversation sandbox.
