Send model requests, tool calls, and backend logs to your OpenTelemetry collector. Configuration 1. Set ARCHESTRA_OTEL_EXPORTER_OTLP_ENDPOINT to the collector's OTLP HTTP base URL, usually port 4318: ARCHESTRA_OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318 2. If required, set ARCHESTRA_OTEL_EXPORTER_OTLP_AUTH_BEARER, or both ARCHESTRA_OTEL_EXPORTER_OTLP_AUTH_USERNAME and ARCHESTRA_OTEL_EXPORTER_OTLP_AUTH_PASSWORD. Bearer authentication takes precedence. 3. Set ARCHESTRA_OTEL_TRACES_SAMPLE_RATE if you need to reduce ingest volume. 4. Restart the backend and send a chat message. 5. Search your tracing backend for service Archestra and a span named chat . Archestra appends /v1/traces and /v1/logs to the base URL. Logs Archestra sends its backend logs to the same collector. Each record carries trace_id and span_id, plus session_id inside an agent session. Your tracing backend uses them to jump from a span to its logs. Content Capture Archestra records message and tool content as span events: | Span | Event | Content | | --- | --- | --- | | LLM | gen_ai.content.prompt | The request messages | | LLM | gen_ai.content.completion | The response text | | MCP | gen_ai.content.input | The tool arguments | | MCP | gen_ai.content.output | The tool result | Each event is truncated to 10,000 characters; ARCHESTRA_OTEL_CONTENT_MAX_LENGTH changes the limit. Capture is on by default. Set ARCHESTRA_OTEL_CAPTURE_CONTENT=false to leave the events out. With content encryption on, capture is off by default. This keeps encrypted content from reaching your telemetry backend as plaintext. ARCHESTRA_OTEL_CAPTURE_CONTENT=true turns it back on. Verbose Tracing By default, Archestra exports only agent spans: LLM calls, MCP tool calls, agent runs, and Knowledge Base calls. Set ARCHESTRA_OTEL_VERBOSE_TRACING=true to also export HTTP routes, outgoing HTTP calls, database queries, and DNS lookups. Use it for debugging. It multiplies span volume. Trace Structure Each agent turn groups its model requests and tool calls in one trace. The root span's route.category tells you how the agent was invoked: | Invocation | route.category | | --- | --- | | Chat UI | chat | | A2A | a2a | | Slack, Microsoft Teams, Telegram | chatops | | Email | email | Calls from your own applications to the LLM Proxy (route.category=llm-proxy) and the MCP Gateway (route.category=mcp-gateway) start their own traces. To group LLM Proxy calls into one trace, send X-Archestra-Session-Id with your conversation ID. Archestra records it as gen_ai.conversation.id. When Guardrails are active, X-Appa-Session-ID takes precedence as the recorded session identity. MCP Gateway spans do not group by X-Archestra-Session-Id. LLM Spans LLM spans use {operation} {model}; Knowledge Base embeddings use embedding {model}. Use these attributes to filter requests and compare token use and cost. | Attribute | Value | | --- | --- | | gen_ai.operation.name | chat or generate_content | | gen_ai.provider.name | The provider, for example openai or anthropic | | gen_ai.request.model, gen_ai.response.model | The requested model and the model that answered | | gen_ai.request.streaming | true or false | | server.address | The provider's base URL | | gen_ai.response.id, gen_ai.response.finish_reasons | The provider's response ID and stop reasons, such as ["stop"] or ["tool_calls"] | | gen_ai.usage.input_tokens, gen_ai.usage.output_tokens, gen_ai.usage.total_tokens | Token counts. Input includes cached tokens. | | gen_ai.usage.cache_read.input_tokens, gen_ai.usage.cache_creation.input_tokens | Prompt-cache reads and writes, part of the input tokens | | archestra.usage.cache_creation.1h_input_tokens | Cache writes at the one-hour TTL (Anthropic and Bedrock) | | gen_ai.usage.reasoning.output_tokens | Reasoning tokens, part of the output tokens (OpenAI and Gemini) | | archestra.cost | Estimated cost in USD. Needs model pricing. | | archestra.billing.mode | metered or subscription | | archestra.trigger.source | Where the call came from, for example api, chat, chatops:slack, or knowledge:embedding | | archestra.auth.method | How the request authenticated, for example virtual_key or oauth_user | | archestra.virtual_key.id, archestra.passthrough_virtual_key.id | The virtual key used, if any | | archestra.app.id, archestra.app.name | The app that made the call, if any | | archestra.external_agent_id | The X-Archestra-Agent-Id header value | | archestra.run.id | The X-Archestra-Run-Id header value | | error.type | The error class, when the call fails | gen_ai.usage.input_tokens includes cached tokens. The llm_tokens_total{type="input"} metric does not. It reads lower when prompt caching is active. Knowledge Base embedding and reranking calls have no agent attributes. Their archestra.trigger.source is knowledge:embedding or knowledge:reranker. MCP Tool Call Spans Each tool call through the MCP Gateway is a span named execute_tool {tool_name}, for example execute_tool github__list_repos. | Attribute | Value | | --- | --- | | gen_ai.operation.name | execute_tool | | gen_ai.tool.name | The full tool name | | gen_ai.tool.call.id | The tool call ID | | mcp.server.name | The MCP server, for example github | | mcp.is_error_result | true when the tool returned an error result | | mcp.blocked | true when a guardrail blocked the call | | mcp.blocked_reason | Why the call was blocked | | error.type | The error class, when the call throws | A blocked call never runs. Its span records the policy decision with span status ERROR and the reason as the status message. Identity Attributes LLM spans, MCP spans, and agent run root spans carry who made the request: | Attribute | Value | | --- | --- | | gen_ai.agent.id, gen_ai.agent.name | The Archestra agent. LLM Proxy calls report LLM Proxy. | | archestra.agent.type | agent, llm_proxy, mcp_gateway, or profile | | archestra.agent.label. | Each agent label, for example archestra.agent.label.environment=production | | archestra.agent.team.ids, archestra.agent.team.names | The agent's teams (arrays) | | archestra.agent.team.label. | The agent's team labels, merged per key across its teams (arrays) | | archestra.user.id, archestra.user.email, archestra.user.name | The user who made the request, when known | | archestra.user.team.ids, archestra.user.team.names | The user's teams (arrays) | | archestra.user.team.label. | The user's team labels, merged per key (arrays) | | gen_ai.conversation.id | The session ID | The LLM Proxy has no labels or teams. Filter its traffic by the archestra.user.team.*, archestra.external_agent_id, or archestra.app.name attributes.8e:T1167,Send key changes, permission updates, and other recorded administrative actions to your security monitoring stack. Archestra exports metadata from the same persisted events available through its audit API as OpenTelemetry logs. Connect Your Collector Use a collector that accepts OTLP over HTTP and forwards logs to your destination. 1. Set these environment variables on the backend: ARCHESTRA_AUDIT_LOG_OTEL_ENABLED=true ARCHESTRA_OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318 ARCHESTRA_AUDIT_LOG_OTEL_ENABLED enables audit export. The OTLP endpoint is shared with backend logs and traces; audit records go to /v1/logs. 2. For authentication, set the bearer token, or the username and password. Use HTTPS for a remote collector. 3. Enable a logs pipeline in your collector, configure its destination, and restart the backend. For example, this diagnostic collector configuration prints incoming log records: receivers: otlp: protocols: http: endpoint: 0.0.0.0:4318 exporters: debug: verbosity: detailed service: pipelines: logs: receivers: [otlp] exporters: [debug] Create a test agent, then search the collector output for instrumentation scope archestra-audit and event name archestra.audit.agent.created. Its log.record.uid matches the event ID returned by GET /api/audit-logs. Backend logs also use this endpoint; filter by the audit scope to separate them. Route Events to Your SIEM Your collector connects Archestra's OTLP logs to the destination your security team uses. Splunk: use the Collector's Splunk HEC exporter and select a Platform index and sourcetype. Microsoft Sentinel: configure the target workspace, authentication and ingestion rules using Azure Monitor OTLP ingestion, or transform records for its Logs Ingestion API. Elastic Security: configure an ingestion endpoint and map the event fields to ECS. Receiving OTLP does not configure security detections. Verify that a test event is searchable in the intended index or table and that your rules read its mapped fields. Event Content and Delivery Audit records identify the action and its outcome; the attribute table below lists the exported fields. All records have INFO severity, including denied and failed actions: write security rules against archestra.audit.outcome. Snapshots, names, emails, raw request URLs, user agents, prompts and responses are excluded. Actor and resource IDs and IP addresses can still identify people; restrict destination access and retention. Some events, including service-account events, have no actor ID. Export runs independently of application log levels and trace sampling. Active trace context may accompany a record; it is optional, and the associated trace may not have been retained. Audit export does not add LLM request or MCP tool-call payloads. Delivery uses an in-memory batch and is best-effort. Outages, full queues or abrupt shutdown can lose exports. Enabling export does not replay earlier events or guarantee that every action produced an audit row. Collector transforms can use these attribute keys: | Information | Attribute | | --- | --- | | Event identity | log.record.uid, archestra.audit.event_sequence | | Schema and organization | archestra.audit.schema_version, archestra.organization.id | | Action and outcome | archestra.audit.action, archestra.audit.outcome | | Actor | archestra.audit.actor_type, archestra.audit.actor_id, archestra.audit.impersonated_by | | Resource | archestra.audit.resource_type, archestra.audit.resource_id | | Request | archestra.audit.request_id, http.request.method, http.route, http.response.status_code, client.address | Missing values are omitted. Behind a trusted reverse proxy, configure ARCHESTRA_TRUST_PROXY to preserve the client IP. Retrieve Events Through the API Use GET /api/audit-logs to retrieve persisted events, including historical records that have not been removed by audit retention. Authenticate with a dedicated service account whose role has auditLog:read and auditLog:admin for organization-wide collection. Pass pagination.nextCursor as the next request's cursor until pagination.hasNext is false. Pages are newest first; use limit=100 for 100 events per page (the default is 20). A scheduled collector needs persistent checkpoints, overlapping date windows, retries and deduplication by deployment and event ID. API responses can contain more sensitive fields than the OTLP export, including snapshots; apply your own allowlist before forwarding them.8f:T928, LLM Proxy Results Archestra handled 851–859 requests per second versus LiteLLM’s 172–175 on the same machine. | Proxy | Requests per Second | Median Added Latency | P95 Added Latency | P99 Added Latency | | --- | ---: | ---: | ---: | ---: | | Archestra | 851.5–859.5 | 58.71 ms | 88.13 ms | 99.44 ms | | LiteLLM | 172.3–174.5 | 266.18 ms | 331.34 ms | 822.92 ms | Each proxy: four logical CPUs, 8 GiB RAM, one worker; 50 concurrent requests with authentication and usage accounting. Per proxy: 10,000 non-streaming requests over two repeats after warmup, zero errors. RPS shows the repeat range, not maximum capacity. Added latency is client response time minus that request’s mock-provider duration. Archestra awaits log writes; LiteLLM writes asynchronously with default content storage. Full methodology and evidence: pinned versions, hardware, configuration, streaming results and raw measurements. MCP Gateway Results Tool calls include authentication, access checks and call logging. | Gateway | Requests per Second | Median Added Latency | P95 Added Latency | P99 Added Latency | | --- | ---: | ---: | ---: | ---: | | Archestra | 608.9 | 79.26 ms | 89.45 ms | 95.01 ms | 16 vCPU / ~63 GiB RAM; one worker, 50 concurrent calls, 600 measured calls and zero errors. Added latency uses the gateway’s internal timer minus the mock MCP server’s duration. It differs from the LLM comparison’s client timer. Reproduction Both tests use local mock servers, with no real inference or provider spend. LLM comparison: Archestra 1.5.0-rc.10 versus LiteLLM 1.106.4, using LiteLLM’s default content omission. Follow the pinned harness in clean-database sensitivity mode; select its archestra and litellm-default results. MCP gateway: the table updates with each Archestra release. The benchmark workflow retains measurements; the benchmark README covers local setup. Run the MCP benchmark from platform/ with Node.js, pnpm, Rust and Docker installed: pnpm install --frozen-lockfile bash benchmarks/ci.sh --requests=300 --stream-requests=300 --repeats=290:Tbab,Claude Code can route model requests through Archestra while using your Claude subscription or an Archestra virtual key. Connect also installs the MCP Gateway and selected shared skills. Requirements Install Claude Code and sign in to your Claude account for subscription inference. You need access to a running Archestra deployment. For virtual-key inference, an administrator must first configure the provider key in Archestra. Connect 1. Open Connect in Archestra and select Claude Code. 2. Copy the command and run it in a terminal. It opens an approval page in your browser. 3. On the approval page, click Approve connection. To change the gateway or leave out the proxy or skills first, open Setup options. If your admin picked provider keys for Claude Code, its models use an Archestra virtual key. Otherwise Claude Code keeps your own subscription or key. 4. When the installer asks Sign in now?, press Enter. Sign in to Archestra in the browser and approve the gateway connection. If you skipped it, start Claude Code, run /mcp, select the Archestra gateway, and choose Authenticate. 5. When the installer asks Start Claude Code now?, press Enter. Claude Code starts a new session with the updated settings. On Windows, or if you answer no, open a new terminal and run the claude command the installer prints last. Setup backs up ~/.claude/settings.json to ~/.claude/settings.json.archestra-backup before its first change. To disconnect, press C in the launch check and select the connection to remove. To restore settings manually, copy the backup over settings.json and remove the gateway with claude mcp remove --scope user ; is its name in /mcp. Verify the Connection Send Reply with connection verified. In Archestra, open Logs → LLM Proxy and find the Claude Code request. A response with subscription billing confirms subscription routing; a virtual-key request confirms API-key routing. Run /mcp and confirm that the gateway is connected. Enable the gateway if it is disabled. Ask Claude Code to list the tools available from that gateway. The list reflects the tools assigned in Archestra and your permissions. If inference works but tools do not, authenticate the gateway separately. If no request appears in the proxy logs, check that you started a new session and that another Claude configuration does not override the generated settings. Gateway Tool Permissions Setup lets Claude Code run gateway tools through run_tool without asking each time. A permission prompt or Claude Code's auto mode then does not stop a task such as a handoff halfway. Setup adds the allow rule to permissions.allow in settings.json. What to know: The rule covers every tool on the gateway. A Claude Code rule cannot match a tool's arguments, so it cannot be narrower. Your access rules and Guardrails still apply to each call. To approve each call yourself, run /permissions in Claude Code and add the same rule as an ask rule. An ask rule wins over an allow rule.91:T17a5,Claude Desktop uses a downloadable setup helper or a terminal command. The setup script supports macOS, Windows, and Linux. Linux requires Anthropic's official Desktop beta. Requirements Install Claude Desktop. The downloadable installer uses Desktop’s built-in runtime. You do not need Node.js, Python, or Claude Code. Subscription access requires your existing Claude subscription. MCP sign-in requires HTTPS, including local deployments. Use a trusted local HTTPS reverse proxy for development. Inference alone supports HTTP on localhost and loopback IP addresses. The Anthropic proxy must forward to Anthropic, without a Vertex AI endpoint override. Setup Connecting the LLM Proxy switches Desktop to third-party inference mode. That mode keeps its own conversation history, so your Claude.ai conversations do not appear there at first. See Import Conversations to bring them over, and Revert before switching. Tools-only setup does not require third-party inference. Open Connect and select Claude Desktop. To pick another gateway, model, or platform, click Change on its line. The platform defaults to your detected operating system. Finish active Desktop tasks before installing. Click Prepare installer, then Download installer, and open the .mcpb file in normal Claude Desktop. Confirm installation in Desktop’s native dialog. The setup helper opens your browser for sign-in and restart confirmation. You can remove the helper from Desktop’s Extensions settings afterward. The Advanced: terminal setup option requires Python 3.9+ and Claude Code for subscription sign-in. It remains available for existing third-party profiles that cannot install Desktop extensions. The installer checks inference before changing your configuration. It backs up changed files, preserves manually created profiles, and restarts Desktop. Rerunning setup replaces the installer-managed connection, including its gateway, skills, and plugins. Installing from another deployment replaces the previous managed connection. If macOS rejects automatic quitting, the installer waits for you to quit from Desktop’s menu. You do not download or import a profile manually. Keep the download and generated command private; they contain an expiring setup ticket. Installation redeems the ticket once. The installer expires after 15 minutes; click Regenerate on Connect for a new one. Subscription Inference Subscription setup opens Claude’s browser authorization page. Its consent screen names the subscription connection “Claude Code”. The CLI does not need to be installed. Only inference access is requested. The resulting token stays on your computer. You do not copy it into Archestra. Valid existing tokens are reused when you rerun setup. Rerun setup if subscription authorization expires or is revoked. Model access and usage limits depend on your Anthropic account. Send a message and check Logs → LLM Proxy for its response and billing mode. Subscription credentials are recorded with subscription billing mode. API-Key Inference Your admin decides which one Desktop uses. When an admin picks provider keys for Claude Desktop under Settings → Connect Page, setup uses a personal Archestra virtual key backed by those keys, if you hold llmVirtualKey:create. The installer applies it without a Claude subscription sign-in. Otherwise setup uses your Claude subscription. Tools, Skills, and Plugins After Desktop restarts, open Settings → Connectors, select archestra, and sign in. In each conversation, enable it under + → Connectors. A connected checkmark in Settings confirms the connection, not its selection for your conversation. Ask Claude to list the gateway's tools to verify availability. When Guardrails are enabled, Desktop's Code and Cowork sessions need this connector enabled to receive remedy plans and approval reviews. The skills and plugins selected on Connect install automatically after Desktop restarts, and plugins show under Customize → Plugins. Setup pins the selected snapshot; rerun Connect to install an updated snapshot. Import Conversations Setup turns on Settings → Import in Desktop. Desktop also offers an import when you start a new chat or task. Sign in to Claude.ai there to copy your chats and projects. You can also import a Claude.ai data export, or earlier Cowork and Code sessions from this computer. Import is a one-time copy, not a sync. Rerun it any time to add newer conversations — it skips the ones already imported. New messages in an already imported conversation are not copied. Conversations you start in third-party mode stay on this computer and never appear on Claude.ai. Importing from Claude.ai needs network access to claude.ai, api.anthropic.com, and storage.googleapis.com. Claude.ai can refuse or delay an export — when your organization disables data export, for example. Revert To return to standard Claude Desktop, choose Anthropic sign-in on Desktop's sign-in screen. Sign in with your original Claude account to access its conversations. Setup and import delete nothing, so your original Claude.ai history is still there. This is Anthropic's documented return path. If your Desktop version does not expose that option, contact your administrator or Anthropic support. Organization policy can hide Claude sign-in. Keep the Claude-3p application data directory. Deleting it can remove conversations created in third-party mode. Removing the setup extension alone does not revert your inference settings. To use another third-party profile, select it in Configure Third-Party Inference and restart Desktop. To return to another deployment, run its installer again. The installer keeps .before-archestra backups of existing configuration files it changes. These backups do not include conversation history. Verify the Connection Send Reply with connection verified. In Logs → LLM Proxy, filter by Claude Desktop to review its requests. Claude Code has a separate filter. Older requests with generic Claude attribution appear as Claude Code.92:T86f,A Microsoft Foundry agent can use Archestra's MCP Gateway as a remote tool server. Foundry continues to host the model; this setup routes tool calls through Archestra, not model inference. Requirements You need a Foundry project and permission to configure agents and project connections. Your Archestra MCP Gateway must be reachable from Foundry over HTTPS. A local localhost address is not reachable from the hosted service. In Archestra, create an MCP Gateway, assign the tools the agent needs, and copy its connection URL. Use a gateway token whose access fits the Foundry project's users. Credentials stored in a Foundry project connection are shared within that project. Connect the Gateway 1. Open your agent in the Foundry portal and add a remote MCP tool. 2. Give it a label, such as archestra, and enter https://api.example.com/v1/mcp/ as the server URL. Use the URL copied from Archestra. 3. Select key-based authentication. Set the credential name to Authorization and its value to Bearer . 4. Save the project connection and attach it to the agent's MCP tool. Select the tools the agent needs and keep tool-call approval enabled for the first test. Foundry stores the credential in its project connection and includes it in gateway requests. See Microsoft's MCP authentication setup and remote MCP connection guide for the controls in your agent type. Verify the Connection Ask the agent to perform a read-only action supported by an assigned tool. Review the requested tool and arguments in Foundry before approving it. Confirm that the response includes the tool's result, then open Logs → MCP Gateway in Archestra and find that call. If Foundry cannot discover tools, check the gateway URL, network reachability, bearer token, and tool assignments. With progressive tool loading enabled, the initial list contains discovery tools rather than every assigned tool; see Progressive Tool Loading. Guardrails only check tool calls when model requests pass through Archestra's LLM Proxy. Because this setup connects only to the MCP Gateway, Guardrails do not apply. Use Foundry's built-in tool approval settings instead.93:T1571,Run an n8n workflow or an Open WebUI chat with Archestra models and tools. Configure model routing and tool access separately, then test each connection. Requirements Use the credential matching the connection you are configuring. For model routing: Configure an OpenAI provider key in Archestra and create a standard virtual key mapped to that provider. Choose a model available under that provider, such as gpt-4o. For tool access: Create an MCP Gateway and generate a gateway token. The client application must be able to reach Archestra's API. The examples use http://localhost:9000/v1/openai; replace this with your deployment's base URL. Applications running inside Docker containers should use a reachable network host such as host.docker.internal rather than localhost. n8n n8n AI workflows can route model inference through the LLM Proxy and execute tools via the MCP Gateway. Connect the Model Use an OpenAI credential to keep the virtual key out of workflow expressions. 1. Open your workflow and attach an AI Agent node to your trigger. 2. Connect an OpenAI Chat Model node to the agent's model input. 3. Configure the OpenAI credential: set Base URL to http://localhost:9000/v1/openai and API Key to your Archestra virtual key. 4. Select a model supported by your provider and save the workflow. 5. If Guardrails are active, add the session header. Configure Guardrails Use n8n's execution ID as the Guardrails session ID so every run keeps its own history. n8n supplies $execution.id when a workflow runs; it stays the same across all model calls in that run. 1. Open the OpenAI credential used by your OpenAI Chat Model node. 2. Turn on Add Custom Header. 3. Set Header Name to X-Appa-Session-ID. 4. Switch Header Value to Expression and enter {{ $execution.id }}. Save the credential. If you call the proxy with an HTTP Request node instead, turn on Send Headers and add X-Appa-Session-ID with {{ $execution.id }}. Keep the virtual key in the credential. For a child workflow, pass the parent workflow's $execution.id in its input data as parentExecutionId. In the child's HTTP Request node, send both headers: X-Appa-Session-ID set to {{ $execution.id }} and X-Appa-Parent-ID set to {{ $json.parentExecutionId }}. Use an HTTP Request node when the OpenAI credential cannot supply both headers. Run the workflow twice and check Logs → LLM Proxy in Archestra. Calls within each run share a session ID, and the two runs get different IDs. Never hardcode a static session ID in the credential. For chats that span multiple workflow runs, see Session Headers. Connect Tools Attach a gateway to give the agent the tools assigned in Archestra. 1. In Archestra, create an MCP Gateway, assign the required tools, and copy the connection URL and gateway token. 2. In n8n, add an MCP Client Tool node to your agent's tools input. 3. Set the endpoint URL to https://api.example.com/v1/mcp/. 4. Choose Bearer Auth and supply your Archestra gateway token. 5. Select the tools to expose to the agent. Choose Streamable HTTP when offered. Archestra also accepts legacy SSE on the same gateway URL. Open WebUI Open WebUI connects to Archestra via its OpenAI-compatible model provider and remote MCP tool server settings. Connect the Model Add Archestra as an OpenAI-compatible connection in Open WebUI. 1. Navigate to Settings → Admin → Connections in Open WebUI. 2. Add a new connection under OpenAI API. 3. Set the API URL to http://localhost:9000/v1/openai and enter your Archestra virtual key as the API key. 4. Verify the connection, save it, and select your model in a new conversation. Configure Guardrails Do not add X-Appa-Session-ID to Open WebUI's global connection headers. Because connection headers apply to every request, setting one there gives all chats the same session ID and mixes their guardrail policies together. To use Guardrails with Open WebUI, route requests through a custom integration that forwards Open WebUI's chat ID in X-Appa-Session-ID. Without that header, Open WebUI follows your unrecognized client setting: allowed without checks by default, or blocked if set to Blocked. Connect Tools Add the gateway as a remote MCP tool server. 1. Navigate to Settings → Admin → Integrations. 2. Under External Tool Servers, add a connection of type MCP (Streamable HTTP). 3. Set the URL to https://api.example.com/v1/mcp/ and configure Bearer authentication with your gateway token. 4. Save and enable the tool server for your chat sessions. Verify the Connection Send Reply with connection verified. to confirm inference. In Archestra, open Logs → LLM Proxy and verify that the request appears with the expected model and virtual key. A 401 status indicates a missing or invalid virtual key. A connection error indicates that the client cannot reach the Archestra API URL. A model error indicates that the requested model is not available under the mapped provider. To test tools, prompt the client to run a read-only action supported by an assigned tool. Check Logs → MCP Gateway in Archestra to confirm tool execution. Guardrails check tool calls only when model requests go through the LLM Proxy; a gateway-only connection does not apply those checks.94:T100b,Keep your SDK's model calls and route them through Archestra for usage logs, spending limits, and Guardrails. The examples below use OpenAI Chat Completions. Requirements Configure an OpenAI provider key and a standard virtual key mapped to it. Set OPENAI_API_KEY in your application's server environment to the virtual key. Replace http://localhost:9000/v1/openai with your reachable Archestra endpoint. A container's localhost refers to that container; use its host-network address, such as Docker Desktop's host.docker.internal, when Archestra runs on the host. Session IDs for Guardrails Use one stable session ID per conversation, including retries and follow-up turns. Set CONVERSATION_ID to a conversation or thread ID your application stores. Reuse it for follow-up turns and retries; create a different ID for each new conversation. These examples assume the packages are installed in your server application. | Header | Value | | --- | --- | | X-Appa-Session-ID | This conversation's ID. | | X-Appa-Parent-ID | The parent's session ID, only for a delegated child. Give the child its own session ID. | Keep the client and key server-side, and scope the session headers to that conversation. A process-wide client with a fixed ID mixes unrelated conversations' policy state. Vercel AI SDK Install ai and @ai-sdk/openai, then configure the OpenAI provider with your proxy URL. import { createOpenAI } from "@ai-sdk/openai"; import { generateText } from "ai"; const openai = createOpenAI({ baseURL: "http://localhost:9000/v1/openai", apiKey: process.env.OPENAI_API_KEY, headers: { "X-Appa-Session-ID": process.env.CONVERSATION_ID! }, }); const result = await generateText({ model: openai.chat("gpt-4o"), prompt: "Reply with connection verified.", }); console.log(result.text); Use .chat() to select Chat Completions explicitly. Keep the key and client in server-side code. Pydantic AI Install pydantic-ai, then pass a custom client to OpenAIProvider. import os from openai import AsyncOpenAI from pydantic_ai import Agent from pydantic_ai.models.openai import OpenAIChatModel from pydantic_ai.providers.openai import OpenAIProvider client = AsyncOpenAI( base_url="http://localhost:9000/v1/openai", api_key=os.environ["OPENAI_API_KEY"], default_headers={"X-Appa-Session-ID": os.environ["CONVERSATION_ID"]}, ) model = OpenAIChatModel("gpt-4o", provider=OpenAIProvider(openai_client=client)) agent = Agent(model) result = agent.run_sync("Reply with connection verified.") print(result.output) OpenAIChatModel selects Chat Completions. Use OpenAIResponsesModel with the same provider for Responses. Mastra Install @mastra/core and configure the agent's custom model endpoint. import { Agent } from "@mastra/core/agent"; const agent = new Agent({ id: "connection-check", name: "Connection Check", instructions: "Answer the user's request.", model: { id: "openai/gpt-4o", url: "http://localhost:9000/v1/openai", apiKey: process.env.OPENAI_API_KEY, headers: { "X-Appa-Session-ID": process.env.CONVERSATION_ID! }, }, }); const result = await agent.generate("Reply with connection verified."); console.log(result.text); Use the base URL, without /chat/completions. The openai/ prefix identifies the provider. Verify the Connection Find the test request in Logs → LLM Proxy with the expected model, virtual key, and timestamp. | Symptom | Check | | --- | --- | | 401 | The application sends the virtual key and the key has an active provider mapping. | | Connection refused or timeout | The application's network can reach the configured host and API port. | | Model error | The mapped provider supports the requested model. | | Unrecognized client or missing policy state | Every call carries the intended conversation's session header. Check Guardrail Clients. | For tool access, connect your SDK's MCP client to an MCP Gateway as well.95:T67f,Tell us what to build, and we build it. Describe the change in a GitHub issue. If the maintainers agree, they implement it with coding agents. Archestra takes contributions as human-written issues, not code. The developer pages in this section are for maintainers, and for anyone who runs Archestra from source. Open an Issue Open an issue on GitHub and pick the template that fits: Create an issue: report a bug or propose a change. Include reproduction steps, your Archestra version, and whether you run Docker or Helm. Add an LLM provider: request support for a new model provider. Add a knowledge connector: request a new data source for knowledge bases. Add an MCP server to the catalog: request a new entry in the MCP Catalog. Maintainers add it. Provider and connector requests need a link to the service's API documentation. Talk to the Team To discuss an idea before you file it, ask in the Slack community. Report a Vulnerability Report security issues privately, never in a public issue, pull request, or Slack channel. Use either channel: Email security@archestra.ai. Open a private security advisory on GitHub. Only maintainers can see it. Include: The affected Archestra version, and whether you run Docker or Helm. Steps to reproduce, or a minimal proof of concept. The impact, such as unauthorized data access, privilege escalation, or code execution. Bug Bounty Archestra has no formal bug bounty program. The security team may award a bounty for a critical vulnerability that is reported privately.96:T1547,One command runs all of Archestra from source, with hot reload. The backend and frontend run on your machine. PostgreSQL and MCP servers run in a local Kubernetes cluster. Tilt starts everything and rebuilds what you change. Prerequisites Node.js 20 to 24. The repository pins 24 in .nvmrc, and pnpm refuses to install on other versions. pnpm. Run corepack enable to use the version pinned in platform/package.json. Rust, installed with rustup. rustup installs the toolchain pinned in platform/rust-toolchain.toml. Tilt, kubectl, and Helm. A local Kubernetes cluster: OrbStack, Docker Desktop with Kubernetes turned on, kind (cluster named kind or archestra), or Colima. Tilt refuses to deploy to any other kubectl context. Start the Environment git clone https://github.com/archestra-ai/archestra.git cd archestra/platform tilt up Tilt creates .env from .env.example if it is missing. Then it installs dependencies and the git pre-commit hook, builds the Rust addons, deploys PostgreSQL, runs migrations, and starts the backend on port 9000 and the frontend on port 3000. The first start takes several minutes. Press the space bar to follow each resource in the Tilt UI at . When pnpm-dev-backend and pnpm-dev-frontend are green, open and sign in as admin@example.com with the password password. tilt down stops the environment. Configure the Environment Settings live in platform/.env. Tilt restarts the backend and frontend when you save it. Every variable is listed in Configuration. To chat without adding a provider key in the UI, set an Anthropic key. Archestra adds it as the organization's Anthropic key at startup: ARCHESTRA_CHAT_ANTHROPIC_API_KEY=sk-ant-... To skip the sign-in screen, set ARCHESTRA_AUTH_DEV_AUTO_AUTHENTICATE_EMAIL=admin@example.com. It has no effect in a production build. Two features need extra services, which start only when you turn them on: ARCHESTRA_CODE_RUNTIME_ENABLED=true turns on the Code Sandbox. Tilt builds its native addon, and the backend starts a Dagger engine in your cluster. ARCHESTRA_FILE_STORAGE_PROVIDER=s3 deploys MinIO as the file store. Everyday Commands Run these from platform/: pnpm lint:fix formats and lints with Biome. pnpm type-check type-checks every workspace. pnpm test runs the unit and integration tests. Backend tests use an in-memory PostgreSQL and do not need Tilt. Without Tilt, build the native addons first: pnpm --filter '@archestra/*-rs' build:dev. pnpm test:e2e:lite:up, then pnpm test:e2e:lite, runs the Playwright suite against a stack in Docker. Stop Tilt first, because both use the same ports. pnpm codegen regenerates the OpenAPI spec, the typed API client, and the generated reference pages. Run it with Tilt up after you change a route's request or response schema. pnpm db:generate generates a migration after you change a Drizzle schema. tilt logs pnpm-dev-backend prints the backend logs. Use pnpm-dev-frontend for the frontend. The pre-commit hook runs the type check, Biome, and Knip (unused exports) in each workspace, plus the migration checks in the backend. It blocks the commit when one fails. tilt trigger database-gui starts Drizzle Studio at to browse the development database. To use psql instead: kubectl exec -n archestra-dev postgresql-0 -- env PGPASSWORD=archestra_dev_password psql -U archestra -d archestra_dev Coding agents read AGENTS.md and the skills in .agents/skills/ for the repository's conventions. Queue a Pull Request Maintainers merge through the GitHub merge queue. Sign in to the GitHub CLI, check out the finished PR head with no local changes, and run this from platform/, with your PR number: pnpm enqueue 1234 It runs the fast checks (types, Biome, Knip, white-label copy, and frontend and shared unit tests), then queues that exact revision. The queue runs the full build and every test suite. The PR must be open, out of draft, and pass its required checks. PR titles follow Conventional Commits (feat:, fix:, docs:). A CI check rejects other titles. Pass --repo owner/name when origin is not the PR's repository. Run a Second Stack Run two branches side by side. Each stack gets its own git worktree, free ports, and its own Kubernetes namespace. From the repository root: git worktree add ../archestra-feature -b feature cd ../archestra-feature/platform pnpm dev:stack:up --detach dev:stack:up copies your .env from the main checkout and gives the stack its own ports. --detach runs Tilt in the background and returns when the frontend responds. pnpm dev:stack:status lists every worktree, whether its stack responds, and its URL. pnpm dev:stack:hydrate copies your LLM provider keys from the main stack, so chat works without entering them again. pnpm dev:stack:down stops the stack in the current worktree. Add a Dependency pnpm refuses package versions published less than seven days ago. When an install fails for that reason, choose an older version. pnpm also skips package install scripts in this repository. Both settings are in platform/pnpm-workspace.yaml. If a package needs its install script to work, run it for that package only: pnpm rebuild 97:T1f4b,Each extension point is a typed registry. Add a provider or connector to one enum, and pnpm type-check lists most of the files that need an entry. This page covers that loop and the steps the compiler misses. Paths are relative to platform/. Add an LLM Provider A new provider gets the LLM Proxy's guardrails, logging, and cost tracking, and shows up in Chat's model picker. Most providers speak OpenAI Chat Completions and reuse OpenAI's schemas and adapter. Copy DeepSeek (deepseek), which is wired into every surface below. Coding agents should load ../.agents/skills/archestra-dev-llm-providers/SKILL.md first. It maps every file a provider touches. Start With the Provider Enum Most of the wiring is a typed record, so the compiler lists it for you. 1. In shared/model-constants.ts, add the provider ID to SupportedProvidersSchema, and :chatCompletions to SupportedProvidersDiscriminatorSchema. 2. Add the provider's schemas to backend/src/types/interaction.ts, then run pnpm codegen. 3. Run pnpm type-check, and add an entry to each record it reports. These include the Chat model fetcher, the client config, the error handlers, the provider test matrix, and the frontend key form. Build an OpenAI-Compatible Provider Types: create backend/src/types/llm-providers// with api.ts, messages.ts, tools.ts, and index.ts. Re-export OpenAI's schemas with .passthrough() to keep custom fields. Export the namespace from backend/src/types/llm-providers/index.ts. Adapter: create backend/src/routes/proxy/adapters/.ts with createOpenAiCompatibleAdapterFactory, and export it from adapters/index.ts. Proxy route: copy backend/src/routes/proxy/routes/deepseek.ts. Register the route IDs in shared/routes.ts, export the plugin from backend/src/routes/index.ts, and add it to registerWorkerRoutes in backend/src/server.ts. Configuration: in backend/src/config.ts, expose llm..baseUrl and chat..apiKey. Add both to .env.example and to the Configuration reference. Build a Provider With Its Own API A provider with its own wire format, such as Anthropic, Gemini, Bedrock, or Cohere, also needs: 1. Zod request, response, message, and tool schemas in backend/src/types/llm-providers//. 2. Implementations of LLMRequestAdapter, LLMResponseAdapter, LLMStreamAdapter, and LLMProvider from backend/src/types/llm-provider.ts. 3. A translator to and from OpenAI Chat Completions, in backend/src/routes/proxy/adapters/-openai.ts and -openai-translator.ts, with a matching test. Finish the Steps the Compiler Misses Model sync: map the provider's models.dev ID in MODELS_DEV_PROVIDER_MAP in shared/model-constants.ts, so model metadata and prices sync. Logos: add frontend/public/icons/.png for the API key form, and a monochrome frontend/public/model-logos/.svg mapped in providerToLogoProvider in frontend/src/lib/provider-logos.ts. Model Router: to make the provider routable, add it to MODEL_ROUTER_SUPPORTED_PROVIDERS and to the router's maps in backend/src/routes/proxy/routes/model-router.ts. A native provider also needs a case in getTranslatedModelRouterProvider. OpenCode: to offer it in OpenCode, add it to OPENCODE_PASSTHROUGH_PROVIDER_ROUTES in shared/opencode-provider-routes.ts. Docs: add a row to the provider table in ../docs/pages/llm-proxy/providers/index.md. To check it works, run the provider matrix, then walk PROVIDER_SMOKE_TEST.md in the running app: pnpm --dir backend exec vitest run src/routes/proxy/routes/provider-matrix.rollback.test.ts The server refuses to start when the Model Router lists in shared/ and model-router.ts disagree. type-check does not catch this. Add a Knowledge Connector Sync an issue tracker, wiki, or drive into a knowledge base on a schedule, so agents can answer from it. A connector is a backend class with a config schema, a checkpoint schema, and a generator that yields document batches. Define the Schemas In backend/src/types/knowledge-connector.ts, add a type literal and the two schemas. Use connectorUrlSchema for URL fields: const ACME = z.literal("acme"); export const AcmeConfigSchema = z.object({ type: ACME, acmeBaseUrl: connectorUrlSchema, projectKeys: z.array(z.string()).optional(), }); export const AcmeCheckpointSchema = z.object({ type: ACME, lastSyncedAt: z.string().optional(), }); Then add ACME to USER_SELECTABLE_CONNECTOR_TYPES, and both schemas to the ConnectorConfigSchema and ConnectorCheckpointSchema unions. type-check does not flag a schema missing from a union. Write the Connector Create backend/src/knowledge-base/connectors/acme/acme-connector.ts, extending BaseConnector: validateConfig(config) checks the config and returns { valid, error? }. testConnection({ config, credentials }) proves the credentials work with one light API call. sync({ config, credentials, checkpoint }) is an async generator that yields document batches with updated checkpoints. Pass the newest item's timestamp to buildCheckpoint, not the clock time. Call the API through fetchWithRetry(), which has a 30-second timeout and exponential backoff, and rateLimit(). Register It 1. Add the factory to connectorRegistry in backend/src/knowledge-base/connectors/registry.ts, and the display name to CONNECTOR_TYPE_LABELS in shared/knowledge-base.ts. 2. Run pnpm codegen, then pnpm type-check to find what the frontend form needs. 3. Create frontend/src/app/knowledge/knowledge-bases/_parts/acme-config-fields.tsx and register it in connector-dialog-config.tsx. 4. Add the icon to frontend/public/icons/ and to CONNECTOR_ICON_MAP in _parts/connector-icons.tsx. type-check does not flag a missing icon. 5. Add ../docs/pages/knowledge/connectors/acme.md, and a row with a anchor in the connectors index. The connector dialog's docs link points at that anchor. To check it works, add tests in acme-connector.test.ts and run them: pnpm --dir backend exec vitest run src/knowledge-base/connectors/acme Add a Retrieval Backend Swap the search index without touching ingestion, querying, or access control. PostgreSQL with pgvector is the only backend Archestra ships. An external index ranks results, while PostgreSQL stays the store for documents, access control, and citations. Implement the Interface Implement every method of KnowledgeRetrievalBackend from backend/src/knowledge-base/retrieval-backend.ts, in retrieval-backends//-retrieval-backend.ts. backend/src/knowledge-base/RETRIEVAL_BACKENDS.md explains each method and the guarantees it must keep. Set requiresResultVerification = true on an external backend. Archestra then reloads every candidate chunk from PostgreSQL and reapplies the connector, ACL, environment, and metadata-filter scope. The external index supplies only the ranking. Wire It In 1. Expose the connection settings under kb in backend/src/config.ts, with matching ARCHESTRA_KNOWLEDGE_BASE_* variables in .env.example and the Configuration reference. 2. Construct the backend in backend/src/knowledge-base/retrieval-backends/registry.ts. The registry has no selector yet, so add an enum setting and a switch where the singleton is built. 3. Add a document-deletion hook. PostgreSQL deletes chunks by foreign-key cascade, which an external index never sees. To check it works, run the query suite. It includes an alternate backend that returns forged fields: pnpm --dir backend exec vitest run src/knowledge-base/query.test.ts98:T2e44,Every permission is a resource:action pair, such as agent:create. A role is a set of these permissions. Docs pages link here by permission name. Access Control explains how roles and per-item grants work together. Predefined Roles Every organization has these four roles. You cannot edit or delete them. Admin Admin holds every permission, including user management, roles, and organization settings. Platform Admin Platform Admin holds every permission except log:admin, auditLog:admin, member:impersonate, and sre:read. It manages users, roles, settings, and resources, but sees only its own logs and audit records and cannot sign in as another member. Because of No Privilege Escalation, it cannot grant a role that holds the withheld permissions. Editor Full access to core resources, but cannot change organization settings or manage users, roles, or identity providers. | Resource | Actions | |----------|--------| | Agents | read, create, delete | | Skills | read, create, delete | | Plugins | read, create, update, delete | | Apps | read, create | | Guardrails Policy | read, update | | LLM Proxy | read, update | | LLM Provider API Keys | read, create | | LLM Virtual Keys | read, create | | LLM Models | read, update | | LLM Limits | read, create, update, delete | | LLM Cost Analytics | read | | MCP Gateways | read, create, delete | | MCP Registry | read, create | | MCP Server Installations | read, create, update, delete | | Environments | read, create, update, delete | | Credentials | read, create | | Knowledge Sources | read, create, update, delete, query | | Chats | read, create, update, delete, full-view | | Projects | read, create, update, delete | | LLM & MCP Logs | read | | API Keys | read, create, delete | | OAuth Clients | read, create | | Users | read | | Roles | read | | Teams | read | | Identity Providers | read | Member Can manage agents, tools, and chat, with read-only access to most other resources. | Resource | Actions | |----------|--------| | Agents | read, create, delete | | Skills | read, create, delete | | Apps | read, create | | LLM Proxy | read | | LLM Provider API Keys | read | | LLM Virtual Keys | read, create | | LLM Models | read | | MCP Gateways | read, create, delete | | MCP Registry | read | | MCP Server Installations | read, create, delete | | Environments | read | | Credentials | read | | Knowledge Sources | read, query | | Chats | read, create, update, delete, full-view | | Projects | read, create, update, delete | | API Keys | read, create, delete | | OAuth Clients | read | | Teams | read | Available Permissions A custom role can hold any of these permissions. To grant an action on a single item, such as one agent, see Granular Access Control. | Permission | Description | |------------|-------------| | ac:read | View custom roles and their permissions | | ac:create | Create new custom roles | | ac:update | Modify custom role permissions | | ac:delete | Delete custom roles | | accessPolicies:read | View access policies for all resource types | | accessPolicies:update | Edit access policies and grant access across all resource types | | agent:read | Open Agents, and use the code sandboxes and files of agents you can use | | agent:create | Create new agents | | agent:delete | Open the trash of deleted agents | | apiKey:read | View API keys | | apiKey:create | Create API keys | | apiKey:delete | Delete API keys | | app:read | Open Apps | | app:create | Create new MCP Apps | | auditLog:read | View audit log records of your own administrative actions | | auditLog:admin | View every audit event in your organization (also requires Read) | | chat:read | View and access chat conversations | | chat:create | Start new chat conversations | | chat:update | Edit chat messages and conversation settings | | chat:delete | Delete chat conversations | | chat:full-view | Show the full chat: the agent picker, model and API key selectors, and expandable tool calls. Without it, chat shows a simpler view | | credential:read | Open Credentials | | credential:create | Create saved credentials | | environment:read | View and list deployment environments | | environment:create | Create deployment environments | | environment:update | Modify deployment environments, including the org default environment | | environment:delete | Delete deployment environments | | guardrailsPolicy:read | View Guardrails policy, batteries, and coverage | | guardrailsPolicy:update | Validate and edit Guardrails policy and manage batteries | | identityProvider:read | View identity provider configurations (SSO) | | identityProvider:create | Set up new identity providers | | identityProvider:update | Modify identity provider settings | | identityProvider:delete | Remove identity providers | | knowledgeSource:read | View Knowledge Bases and Connectors | | knowledgeSource:create | Create Knowledge Bases and Connectors | | knowledgeSource:update | Modify Knowledge Bases and Connectors | | knowledgeSource:delete | Delete Knowledge Bases and Connectors, view the deleted ones, and restore them | | knowledgeSource:query | Query knowledge sources for information retrieval | | llmCost:read | View organization-wide LLM usage cost statistics and analytics | | llmLimit:read | View token usage limits | | llmLimit:create | Create new usage limits | | llmLimit:update | Modify existing usage limits | | llmLimit:delete | Remove usage limits | | llmModel:read | View synced LLM models and capabilities | | llmModel:update | Sync the model catalog and see every model, including ones not shared with you | | llmProviderApiKey:read | Open LLM provider API keys | | llmProviderApiKey:create | Add new LLM provider API keys | | llmProxy:read | View the LLM Proxy and its connection details | | llmProxy:update | Modify LLM Proxy configuration | | llmVirtualKey:read | Open LLM virtual keys | | llmVirtualKey:create | Create LLM virtual keys | | log:read | View your own LLM proxy, MCP tool call, and Guardrails consult logs in the active organization, and view and resolve Guardrails yells | | log:admin | View every LLM, MCP, and Guardrails consult log in your organization (also requires Read) | | mcpGateway:read | Open MCP Gateways | | mcpGateway:create | Create new MCP gateways | | mcpGateway:delete | Open the trash of deleted MCP gateways | | mcpRegistry:read | Open the MCP registry and use its built-in servers | | mcpRegistry:create | Add servers to the MCP registry | | mcpServerInstallation:read | View installed MCP servers and their status | | mcpServerInstallation:create | Install MCP servers from the registry | | mcpServerInstallation:update | Modify installed MCP server configuration | | mcpServerInstallation:delete | Uninstall, view deleted, and restore MCP servers within your access | | member:read | View organization members and their roles | | member:create | Add new members to the organization and manage invitations | | member:update | Change member roles and settings | | member:delete | Remove members from the organization | | member:impersonate | Temporarily sign in as another member to see the app with their access (role debugging) | | oauthClient:read | Open OAuth client registrations | | oauthClient:create | Create OAuth client registrations | | organizationSettings:read | View every organization settings page, including messaging channels | | organizationSettings:update | Change organization settings, messaging channels, and site notifications | | plugin:read | View plugins and their file metadata | | plugin:create | Create plugins | | plugin:update | Modify plugin metadata and files | | plugin:delete | Delete plugins | | project:read | View projects, their schedules, and your own sessions inside them | | project:create | Create projects and schedules, and trigger schedule runs | | project:update | Edit project descriptions, instructions, sharing, and schedules | | project:delete | Delete projects and schedules | | serviceAccount:read | Open Service Accounts | | serviceAccount:create | Create service accounts | | skill:read | Open Skills | | skill:create | Create new agent skills | | skill:delete | Permanently delete skills from the trash | | sre:read | Use the SRE agent and its Kubernetes tools, which read this installation's pods, logs, and specs | | team:read | View teams and their members | | team:create | Create new teams | | team:update | Modify team settings | | team:delete | Delete teams |99:T827,Automate anything the web app does from scripts and CI: create agents, install MCP servers, change policies, and export costs and logs. The web app runs on this same API, and every endpoint checks the same permissions. This API manages Archestra. To send model requests or call MCP tools, use the LLM Proxy or an MCP Gateway instead. Authentication Send an API key in the Authorization header, without a Bearer prefix: curl -H "Authorization: arch_..." https://archestra.example.com/api/agents A request without a valid key returns 401. A key whose role lacks the endpoint's permission returns 403. Use one of two kinds of key: Personal API key: acts as you, with your current permissions. Use it for your own scripts. Service account key: belongs to the organization, so it keeps working after the person who made it leaves. Use it for CI, scheduled jobs, and shared integrations. Personal API Keys Click your name in the sidebar, go to API Keys, and click Create API Key. Copy the key right away. You cannot view it again. Service Accounts 1. Go to Settings → Service Accounts and click Create service account. 2. Give it a role that holds only the permissions the job needs. 3. Open the account and click Create API key. To export organization-wide costs, the role needs llmCost:read. Add member:read to break costs down by person. To export every log, the role needs log:read and log:admin. To rotate a key, create a new one, move your clients to it, and delete the old one. Disabling or deleting the account stops all its keys. Leave Out Agent Tools Add includeTools=false to read agents without their tools. The tools are most of the response, because each one carries its name and description. These endpoints include them by default: GET /api/agents GET /api/agent-catalog GET /api/mcp-gateways/default curl -H "Authorization: arch_..." "https://archestra.example.com/api/agents?includeTools=false" toolsCount and subagentsCount are always present. With includeTools=false, tools is an empty array. It means "not requested", not "no tools assigned". Endpoints :::swagger-ui :::9a:T355e0,Let an agent run Archestra for you: ask it to create an agent, install an MCP server, or build an app, and it calls these tools. The Archestra MCP Server is built into every deployment and acts as the person using the agent, with their permissions. Every tool name starts with archestra__. This page lists tools by their short name. Give an Agent These Tools Pick these tools like any other MCP server's tools, on an agent's Tools, Skills & Knowledge tab or a gateway's Tools & Knowledge settings: Manual: assign the tools you want. All: the agent gets every tool the person can use, but built-in tools start out excluded. Remove a tool from the exclusions to allow it. New agents include todo_write and query_knowledge_sources. Turning on a feature adds its own default tools. query_knowledge_sources appears only when the agent or gateway has a knowledge base or connector attached. Permissions Each tool needs the permission in the last column of its table. A person sees only the tools their permissions allow: without knowledgeSource:create, for example, create_knowledge_base is hidden. A tool marked † has an extra condition, described in its entry. Guardrails policies apply on top of these permissions. Tools Reference Identity | Tool | Description | Permission | |------|-------------|--------------------------| | whoami | Returns the name and ID of the current agent. | None | whoami Required RBAC permission: None This tool takes no arguments. Output | Field | Type | Required | Description | |-------|------|----------|-------------| | agentId | string | Yes | The ID of the current agent. | | agentName | string | Yes | The display name of the current agent. | Chat | Tool | Description | Permission | |------|-------------|--------------------------| | todo_write | Write todos to the current conversation. | None | | ask_user | Ask the user to pick from a short list of options. | None | todo_write Required RBAC permission: None Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | todos | object[] | Yes | Array of todo items to write to the conversation. | | todos[].id | integer | Yes | Unique identifier for the todo item. | | todos[].content | string | Yes | The content or description of the todo item. | | todos[].status | "pending" \| "in_progress" \| "completed" | Yes | The current status of the todo item. | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | success | true | Yes | Whether the write succeeded. | | todoCount | integer | Yes | How many todo items were written. | ask_user Required RBAC permission: None Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | question | string | Yes | The question shown above the options, as plain text. Put links and commands in your reply text. | | header | string | No | A very short label shown as the question's tab, e.g. 'Visibility'. | | options | object[] | Yes | The options the user can pick. Labels must be unique. | | options[].label | string | Yes | The option shown to the user. | | options[].description | string | No | Optional extra detail shown next to the option. | | allowMultiple | boolean | No | When true, the user may select more than one option. Defaults to false (exactly one). | | remedy_offer_ids | string[] | No | Exact offer IDs from the blocked ruling that this question asks the user to decide: a review execute_remedy_plan requires, or a plan that would prevent what the user asked for. Say in the question what it would prevent. Omit for ordinary questions. | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | action | "accept" \| "decline" \| "cancel" | Yes | Whether the choice form was submitted, declined, or canceled. | | selected | string[] | Yes | The labels the user selected. Empty when declined or canceled. | | text | string | No | What the user typed instead of picking an option. | | timedOut | boolean | No | True when the question expired without an answer. | Tool Discovery | Tool | Description | Permission | |------|-------------|--------------------------| | search_tools | Search the tools available to this agent and to you on demand. | None | | run_tool | Dispatch to any tool available to this agent, including built-in platform tools, agent delegation tools ('agent-'), or third-party MCP tools exposed through the MCP Gateway (e.g. | None | search_tools Required RBAC permission: None Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | query | string | Yes | Keywords for the capability you need — combine the action (verb + object) with the server/product name when you know it, e.g. 'github search repositories' or 'slack send message'. Avoid querying with a bare product/server name on its own. Results are keyword-ranked across tool names, descriptions, and argument names/descriptions. If nothing fits, reformulate with different keywords and search again rather than settling for a poor match. | | limit | integer | No | Maximum number of matching tools to return, at most 20. A larger value returns 20. | | mode | "keyword" \| "regex" | No | Search mode. 'keyword' (default) keyword-ranks the query across tool fields. 'regex' treats query as a case-insensitive regular expression matched against tool names, titles, and descriptions — use it when you know a naming pattern, e.g. '^github__' or 'search\|find'. | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | total | integer | Yes | Number of returned tools. | | matchCount | integer | Yes | Total tools matching the query before the limit was applied (>= total). | | truncated | boolean | Yes | True when matchCount exceeds the returned tools (results cut by limit). | | hint | string \| null | Yes | Actionable guidance when results were truncated or empty (an empty result also names which query terms matched no tool text). | | tools | object[] | Yes | | | tools[].toolName | string | Yes | Exact tool name to pass to run_tool. | | tools[].description | string \| null | Yes | Short tool description, if available. | | tools[].source | "archestra" \| "mcp" \| "agent_delegation" | Yes | Where the tool comes from. | | tools[].server | string \| null | Yes | MCP server prefix for third-party MCP tools when available. | | tools[].available | boolean | Yes | False when the tool's MCP connection is not installed; it stays discoverable but cannot run until reconnected. | | tools[].unavailableReason | string \| null | Yes | Compact reason and recovery action when available is false; null otherwise. | | tools[].params | string | Yes | Compact one-line input signature — a summary, not the full schema. Parameters are joined by '; ', each rendered as name: where ! marks required and ? optional. Object parameters are expanded up to two levels as {child:type{grandchild:type}, …}, enums as enum(), and a trailing — description is added when available. A trailing … on a type marks an object whose content is not fully shown (freeform or more deeply nested) — consult the task instructions or the full schema for its shape. Empty string when the tool takes no input. Pass matching values inside tool_args when calling run_tool; if a call is rejected as invalid, the error describes the expected input (for third-party tools, the full input schema). | run_tool Required RBAC permission: None Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | tool_name | string | Yes | Name of the tool to invoke. Use the exact name as it appears in the tools list, e.g. 'archestrawhoami', 'context7resolve-library-id', or an agent delegation name 'agent-'. | | tool_args | object | No | Arguments object for the target tool; must match its input schema. | Skills | Tool | Description | Permission | |------|-------------|--------------------------| | list_skills | List the Agent Skills available in this organization — one line per skill (name and description). | skill:read | | load_skill | Load a specialized Agent Skill — a reusable SKILL.md instruction set. | skill:read | | create_skill | Create a new Agent Skill from a SKILL.md manifest. | skill:create | | update_skill | Update an existing Agent Skill from a SKILL.md manifest. | update on the skill (granted per item) | | edit_skill | Make a targeted edit to an existing Agent Skill without resending the whole SKILL.md. | update on the skill (granted per item) | list_skills Required RBAC permission: skill:read This tool takes no arguments. load_skill Required RBAC permission: skill:read Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | name | string | Yes | The skill to load, as named by list_skills. | | path | string | No | Optional. Omit (or pass an empty string) to load the skill's instructions and bundled-file list. Pass a resource path from that list (e.g. references/REFERENCE.md) to read one bundled file instead. | create_skill Required RBAC permission: skill:create Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | initialGrants | object[] | No | | | initialGrants[].subject | object | Yes | | | initialGrants[].subject.type | "user" \| "team" \| "serviceAccount" \| "role" \| "organization" | Yes | | | initialGrants[].subject.id | string \| "*" | Yes | | | initialGrants[].actions | string[] | Yes | | | content | string | Yes | A complete SKILL.md manifest: a YAML frontmatter block with name and description (and optional license, compatibility, allowed-tools, agent, templated, metadata), followed by the Markdown instruction body. Set templated: true to render the body through Handlebars (e.g. {{user.name}}) at activation. allowed-tools is a space-separated list of tools the skill is pre-approved to use. agent names an agent the skill runs in — when set, activating the skill delegates it to that agent instead of loading the instructions into the caller's context. | | files | object[] | No | Optional bundled resource files. Each is { path, content } with text content; the path prefix classifies the file — references/ for docs, scripts/ for code, assets/ for other files. | | files[].path | string | Yes | Resource path, e.g. references/API.md or scripts/run.py | | files[].content | string | Yes | Text content of the file | | files[].encoding | "utf8" \| "base64" | No | | update_skill Required RBAC permission: update on the skill (granted per item) Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | name | string | Yes | The current name of the skill to update, as named by list_skills. | | content | string | Yes | A complete SKILL.md manifest: a YAML frontmatter block with name and description (and optional license, compatibility, allowed-tools, agent, templated, metadata), followed by the Markdown instruction body. Set templated: true to render the body through Handlebars (e.g. {{user.name}}) at activation. allowed-tools is a space-separated list of tools the skill is pre-approved to use. agent names an agent the skill runs in — when set, activating the skill delegates it to that agent instead of loading the instructions into the caller's context. | | files | object[] | No | Optional. WHEN PROVIDED, REPLACES THE SKILL'S ENTIRE bundled file set. Omit it to leave the existing resource files untouched. There is no per-file patch: to change one file you must resend all of them — read the current files back first with load_skill (with and without a path). | | files[].path | string | Yes | Resource path, e.g. references/API.md or scripts/run.py | | files[].content | string | Yes | Text content of the file | | files[].encoding | "utf8" \| "base64" | No | | edit_skill Required RBAC permission: update on the skill (granted per item) Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | name | string | Yes | The current name of the skill to edit, as named by list_skills. | | baseVersion | integer | Yes | The version the edit is based on — the version shown on the / frame you loaded with load_skill. The edit is rejected if the skill's head has moved past it. | | path | string | No | Omit (or pass an empty string) to edit the SKILL.md body; pass a bundled file path (from the list) to edit that file instead. Only text (utf8) files are editable — binary assets are not. | | edits | object[] | No | str_replace edits applied in order to the target; the whole edit is atomic (any failure leaves the skill unchanged). This is the way to change a large SKILL.md without resending it all. Pass either edits or replacementContent, never both. | | edits[].old_str | string | Yes | Exact text to replace; must occur exactly once in the target (add surrounding context to disambiguate). | | edits[].new_str | string | Yes | Replacement text (may be empty to delete). | | replacementContent | string | No | The complete new content of the target, replacing it outright with no old_str matching — use it for a small file or a full rewrite. Prefer edits for the SKILL.md body so you don't resend the whole thing. Pass either edits or replacementContent, never both. | Files | Tool | Description | Permission | |------|-------------|--------------------------| | search_files | List or search the conversation's persistent files. | agent:read | | read_file | Read a persistent file directly, without copying it into the sandbox. | agent:read | | save_file | Write bytes you are providing inline in this call — text or base64 included in the arguments — to the conversation's persistent files. | agent:read | | edit_file | Edit an existing persistent file by replacing a snippet, keeping its id and filename. | agent:read | | delete_file | Permanently delete a persistent file, identified by id (the id or ref from search_files, or a fileId from save_file) or by filename. | agent:read | | copy_file | Exchange a file between this chat and the app the user has open: copy a chat/project file or a chat attachment INTO the open app's file store (so the app can load it), or copy a file OUT of the app... | agent:read | search_files Required RBAC permission: agent:read Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | query | string | No | Case-insensitive substring matched against filenames only. Omit it (or pass empty) to list the files (the first 200). | | scope | "chat" \| "app" | No | "chat" (default) = this chat's files; "app" = the files of the app the user has open, which is how you find what the app has produced before copying one out with copy_file. | | project_id | string | No | Use this project's files instead of the current chat's — how you reach project files when working outside a chat (get_project returns the id). Only projects you own or that are shared with you can be used. Cannot be used from a chat that already belongs to a different project, nor combined with scope: "app". | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | files | object[] | Yes | | | files[].id | string \| null | Yes | Row id (UUID), or null for a hand-placed file with no row. | | files[].ref | string | Yes | Stable handle for this file — pass it to read_file / upload_file / edit_file / delete_file. Works for hand-placed files too (where id is null). | | files[].filename | string | Yes | | | files[].mimeType | string | Yes | | | files[].sizeBytes | number | Yes | | | files[].createdAt | string | Yes | | read_file Required RBAC permission: agent:read Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | string | No | Id or ref of the file to read — the id or ref from search_files, or a fileId from save_file. | | filename | string | No | Filename to read instead of id; rejected as ambiguous if more than one file shares the name. | | offset | integer | No | 1-based line number to start reading from. Defaults to 1. | | limit | integer | No | Maximum number of lines to read. Defaults to 2000. | | project_id | string | No | Use this project's files instead of the current chat's — how you reach project files when working outside a chat (get_project returns the id). Only projects you own or that are shared with you can be used. Cannot be used from a chat that already belongs to a different project, nor combined with scope: "app". | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | kind | "text" \| "image" | Yes | text = numbered lines in the text content; image = the file is returned as an inline image block. | | fileId | string \| null | Yes | The file's id, or null for a hand-placed file with no row. | | filename | string | Yes | | | mimeType | string | Yes | | | sizeBytes | number | Yes | | | totalLines | number | No | | | startLine | number | No | | | returnedLines | number | No | | | truncated | boolean | No | True when more lines follow the returned window (raise offset to continue). | | content | string | No | The returned window's text, WITHOUT the line numbers — the file's own bytes. Present for text reads so a structured consumer (an app via archestra.tools.call, which unwraps to structuredContent and never sees the text block) gets usable content instead of only metadata. The numbered rendering stays in the text output, where line numbers are what makes edit_file addressable. | save_file Required RBAC permission: agent:read Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | filename | string | Yes | Plain filename including extension (e.g. "joke.md"). No paths. | | content | string | No | UTF-8 text content of the file. | | contentBase64 | string | No | Base64-encoded binary content. | | mimeType | string | No | Optional MIME type. Sniffed from the bytes when omitted. | | overwrite | boolean | No | Replace an existing file of the same name in place, keeping its id. Default false errors if the name is already taken. | | project_id | string | No | Use this project's files instead of the current chat's — how you reach project files when working outside a chat (get_project returns the id). Only projects you own or that are shared with you can be used. Cannot be used from a chat that already belongs to a different project, nor combined with scope: "app". | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | fileId | string | Yes | | | filename | string | Yes | | | projectName | string \| null | Yes | Owning project when saved into a project; null otherwise. | | mimeType | string | Yes | | | sizeBytes | number | Yes | | | overwritten | boolean | Yes | True when an existing same-named file was replaced in place. | edit_file Required RBAC permission: agent:read Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | string | No | Id of the file to edit — the id or ref from search_files, or a fileId from save_file. | | filename | string | No | Filename to edit instead of id; rejected as ambiguous if more than one file shares the name. | | old_string | string | Yes | The exact text to replace; must match the file's current content (read it first with read_file). Include enough surrounding context to be unique unless replace_all is set. | | new_string | string | Yes | The text to insert in place of old_string. | | replace_all | boolean | No | Replace every occurrence of old_string. Default false replaces a single occurrence and errors if old_string is not unique. | | project_id | string | No | Use this project's files instead of the current chat's — how you reach project files when working outside a chat (get_project returns the id). Only projects you own or that are shared with you can be used. Cannot be used from a chat that already belongs to a different project, nor combined with scope: "app". | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | fileId | string | Yes | | | filename | string | Yes | | | mimeType | string | Yes | | | sizeBytes | number | Yes | | | replacements | number | Yes | How many occurrences of old_string were replaced. | delete_file Required RBAC permission: agent:read Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | string | No | Id of the file to delete — the id or ref from search_files, or a fileId from save_file. | | filename | string | No | Filename to delete instead of id; rejected as ambiguous if more than one file shares the name. | | project_id | string | No | Use this project's files instead of the current chat's — how you reach project files when working outside a chat (get_project returns the id). Only projects you own or that are shared with you can be used. Cannot be used from a chat that already belongs to a different project, nor combined with scope: "app". | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | fileId | string | Yes | The deleted file's id, or its ref for a rowless file. | | filename | string | Yes | | | deleted | true | Yes | | copy_file Required RBAC permission: agent:read Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | from | object | Yes | Where the bytes come from: {"type":"chat_file","id"\|"filename"} \| {"type":"chat_attachment","attachmentId"\|"filename"} \| {"type":"app_file","id"\|"filename"}. | | from.type | "chat_file" \| "chat_attachment" \| "app_file" | Yes | | | from.id | string | No | When type="chat_file": File id from search_files. When type="app_file": File id in the app's store. | | from.filename | string | No | When type="chat_file": Filename instead of id; ambiguous names rejected. When type="chat_attachment": Original filename of an attachment in this conversation (when you have no id). If the same name was attached more than once, the newest one wins. When type="app_file": Filename instead of id. | | from.attachmentId | string | No | Id of an attachment uploaded to THIS conversation. | | to | object | Yes | Where the copy lands. | | to.scope | "chat" \| "app" | Yes | "app" = the open app's per-viewer store; "chat" = this chat's files (the project's files when this chat belongs to a project). | | to.filename | string | No | Destination filename; defaults to the source's name. Plain filename, no paths. | | to.overwrite | boolean | No | Replace an existing same-named destination file in place. Default false: a duplicate name is an error. | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | fileId | string | Yes | Id of the copy at the destination. | | filename | string | Yes | | | mimeType | string | Yes | | | sizeBytes | number | Yes | | | destination | "conversation" \| "project" \| "app" | Yes | The scope the copy landed in. | | overwritten | boolean | Yes | | Code Sandbox These tools are served only when the code runtime is enabled — set ARCHESTRA_CODE_RUNTIME_DAGGER_RUNNER_HOST, or ARCHESTRA_CODE_RUNTIME_ENABLED=true together with an orchestrator kubeconfig. Without it they do not appear in tools/list. The Code Sandbox page covers what the runtime is and how an agent uses it. | Tool | Description | Permission | |------|-------------|--------------------------| | run_command | Execute a shell command in the conversation's sandbox (Debian, working dir /home/sandbox). | agent:read | | download_file | Copy a file that already exists at a path in the conversation's sandbox into the conversation's persistent files. | agent:read | | upload_file | Place a file into the conversation's sandbox at a path, from a chat attachment, inline base64, inline text, or one of your persistent files. | agent:read | run_command Required RBAC permission: agent:read Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | command | string | Yes | Shell command to execute (bash). Runs in the sandbox's working directory (or cwd when provided). Returns text output only — use download_file for generated files. | | cwd | string | No | Optional absolute path inside the container. Defaults to the sandbox's working directory (/home/sandbox). | | timeoutSeconds | integer | No | Optional wall-clock limit in seconds, capped at the deployment maximum. | | target | object | No | Which sandbox to use. Omit (or leave empty) for the conversation's default sandbox (created on first use), which holds the conversation's attachments. Pass { "fresh": true } for a new empty sandbox, or { "id": "" } to target a specific one. | | target.fresh | boolean | No | Set true for a brand-new empty sandbox, without the conversation's attachments or earlier work; its id is returned. | | target.id | string | No | An existing sandbox id (UUID) returned by an earlier call. | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | commandId | string | Yes | | | sandboxId | string | Yes | | | command | string | Yes | | | cwd | string \| null | Yes | | | stdout | string | Yes | | | stderr | string | Yes | | | exitCode | number | Yes | | | durationMs | number | Yes | | | timedOut | boolean | Yes | | | truncated | boolean | Yes | | | binaryStripped | boolean | Yes | True when NUL bytes were stripped from stdout/stderr before storage. | | stagingNotices | string[] | Yes | Notices about chat attachments that could not be auto-staged (e.g. too large). Empty when all attachments are available in the sandbox. | download_file Required RBAC permission: agent:read Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | path | string | Yes | Path to the file inside the container — absolute, or relative to the sandbox's working directory. | | mimeType | string | No | Optional MIME type recorded with the file. Sniffed from the bytes when omitted. | | overwrite | boolean | No | Replace an existing same-named persistent file in place, keeping its id. Default false errors if the name is already taken. | | target | object | No | Which sandbox to use. Omit (or leave empty) for the conversation's default sandbox (created on first use), which holds the conversation's attachments. Pass { "fresh": true } for a new empty sandbox, or { "id": "" } to target a specific one. | | target.fresh | boolean | No | Set true for a brand-new empty sandbox, without the conversation's attachments or earlier work; its id is returned. | | target.id | string | No | An existing sandbox id (UUID) returned by an earlier call. | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | fileId | string | Yes | | | sandboxId | string | Yes | | | path | string | Yes | | | mimeType | string | Yes | | | sizeBytes | number | Yes | | | stagingNotices | string[] | Yes | Notices about chat attachments that could not be auto-staged (e.g. too large). Empty when all attachments are available in the sandbox. | | overwritten | boolean | Yes | True when an existing same-named file was replaced in place. | upload_file Required RBAC permission: agent:read Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | path | string | Yes | Destination path inside the container — absolute under /skills or /home/sandbox, or relative to the sandbox's working directory. | | source | object | Yes | Where the file bytes come from. One of four shapes, each tagged by a type: a chat attachment ({"type":"chat_attachment","attachmentId"\|"filename":...}), inline base64 ({"type":"base64","dataBase64":...}), inline text ({"type":"text","text":"print(1)"}), or a file from the user's persistent files ({"type":"my_file","filename":...}, found via search_files). Use this to place input bytes; to create a file the sandbox will then run or read, write it with run_command instead. | | source.type | "chat_attachment" \| "base64" \| "text" \| "my_file" | Yes | | | source.attachmentId | string | No | Id of an attachment in the current conversation. The bytes are copied directly and never enter your context. | | source.filename | string | No | When type="chat_attachment": Original filename of an attachment in this conversation (when you have no id). If the same name was attached more than once, the newest one wins. When type="my_file": Exact filename of a persistent file (when you have no id). | | source.dataBase64 | string | When type="base64" | Base64-encoded file bytes. | | source.mimeType | string | No | | | source.originalName | string | No | | | source.text | string | When type="text" | UTF-8 text content of the file. | | source.id | string | No | Id or ref of a persistent file, as returned by search_files (id for stored files, ref for hand-placed ones). | | target | object | No | Which sandbox to use. Omit (or leave empty) for the conversation's default sandbox (created on first use), which holds the conversation's attachments. Pass { "fresh": true } for a new empty sandbox, or { "id": "" } to target a specific one. | | target.fresh | boolean | No | Set true for a brand-new empty sandbox, without the conversation's attachments or earlier work; its id is returned. | | target.id | string | No | An existing sandbox id (UUID) returned by an earlier call. | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | uploadId | string | Yes | | | sandboxId | string | Yes | | | path | string | Yes | | | mimeType | string | Yes | | | sizeBytes | number | Yes | | Apps | Tool | Description | Permission | |------|-------------|--------------------------| | scaffold_app | Create a new interactive app (dashboard, form, tracker, game, or any custom UI) seeded from the default starter template. | app:create | | refine_app | Clarify what an existing app should be and record it as a persisted product spec, between scaffold_app and edit_app. | update on the app (granted per item) | | list_apps | List apps visible to the caller, optionally filtered by name or labels — use it to find an app's id. | app:read | | list_app_versions | List the immutable versions of an app, newest first, without returning their HTML. | app:read | | render_app | Render an existing app by id, if the caller may view it. | app:read | | read_app | Return an app's stored HTML (pre-injection — exactly what was saved, without the platform SDK or base stylesheet) plus its version, byte size, name, and scope. | app:read | | restore_app_version | Restore a historical app version directly on the server as a new head version. | update on the app (granted per item) | | edit_app | The single path for any change to an app's HTML: pass edits for targeted str_replace changes, imageReplacements to replace embedded images from chat attachments without sending base64 through the m... | update on the app (granted per item) | | set_app_tools | Replace an existing app's assigned upstream tools with exactly the set you pass (the full desired list; [] clears all). | update on the app (granted per item) | | set_app_labels | Replace an app's labels with exactly the set you pass ([] clears them). | update on the app (granted per item) | | set_app_lock | Lock or unlock an app. | update on the app (granted per item) | | validate_app | The pre-publish gate for an app's head version: static structural checks (findings, each carrying its own specific message) plus the most recent live-render diagnostics (live), with ok true w... | app:read | | publish_app | Share an app by granting read and use access to specific teams (scope: team, teams: names or IDs) or the whole organization (scope: org). | manage-permissions on the app (granted per item) | | preview_app_tool | Run one of an app's assigned MCP tools server-side, exactly as the rendered app would (as you, the viewing user, with your MCP credentials), and return its real output. | update on the app (granted per item) | | get_app_diagnostics | Check how the app's current version rendered for you. | app:read | | delete_app | Soft-delete an app the caller owns or administers, and remove its MCP backing so it is no longer served. | delete on the app (granted per item) | | app_data_get | Read a value from the calling app's data store (per-user or shared partition). | app:read | | app_data_set | Write a value to the calling app's data store (per-user or shared partition). | update on the app (granted per item) | | app_data_list | List all entries in one partition of the calling app's data store. | app:read | | app_data_delete | Delete a key from the calling app's data store (per-user or shared partition). | update on the app (granted per item) | | llm_complete | Run a single LLM completion for the calling app (backs archestra.llm.complete). | app:read | scaffold_app Required RBAC permission: app:create Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | initialGrants | object[] | No | | | initialGrants[].subject | object | Yes | | | initialGrants[].subject.type | "user" \| "team" \| "serviceAccount" \| "role" \| "organization" | Yes | | | initialGrants[].subject.id | string \| "*" | Yes | | | initialGrants[].actions | string[] | Yes | | | name | string | Yes | App name. | | description | string | No | Optional description. | | uiPermissions | object | No | Optional iframe permissions (camera/microphone/geolocation/clipboardWrite). | | uiPermissions.camera | object | No | | | uiPermissions.microphone | object | No | | | uiPermissions.geolocation | object | No | | | uiPermissions.clipboardWrite | object | No | | | icon | string | No | Optional display icon for the app, as a single emoji character (e.g. "📊") chosen to suit what the app does. Omitted leaves the app with the generic app glyph. | | labels | object[] | No | Optional key-value labels for organization and categorization. | | labels[].key | string | Yes | | | labels[].value | string | Yes | | | tools | string[] | No | Upstream MCP tool names to assign to the new app (e.g. from search_tools), callable from its HTML via archestra.tools.call with the viewing user's credentials. Omitted leaves the app with no assigned tools. | | project_id | string | No | Link the new app into this project (from list_projects) so it is listed with the project's files. You need access to the project. Omitted creates a standalone app. | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | id | string | Yes | | | name | string | Yes | | | description | string \| null | Yes | | | scope | "personal" \| "team" \| "org" | Yes | | | latestVersion | number | Yes | | | labels | object[] | Yes | Key-value labels for organization/categorization. | | labels[].key | string | Yes | The label key. | | labels[].value | string | Yes | The label value. | | warnings | string[] | No | Soft save-time validation warnings about the html (the save succeeded); fix them via edit_app. | | tools | string[] | No | The app's assigned tool names after this call (present when the tools param was given). | | status | "ok" \| "partial" | No | Absent or "ok" on full success. "partial" means the app was created (see id) but assigning its tools failed — the app exists; assign them with set_app_tools rather than re-scaffolding. | refine_app Required RBAC permission: update on the app (granted per item) Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | appId | string | Yes | The app id to refine. | | questions | object[] | No | Up to 3 clarifying questions to ask the user before consolidating the spec. | | questions[].id | string | Yes | Stable key the answer is returned under. | | questions[].prompt | string | Yes | The question shown to the user. | | questions[].options | string[] | No | When present, the question is single-select over these plain-string option labels, e.g. ["Light", "Dark"] — never {label, value} objects; otherwise it is free-text. | | spec | object | No | The consolidated product requirements to persist on the app (features/data/ui/tools — no implementation stack). | | spec.summary | string | Yes | One-line summary of what the app is for. | | spec.features | string[] | Yes | Concrete capabilities the app should provide. | | spec.data | string \| null | No | What the app reads/persists via the App Data Store — a free-form prose string, not a structured object. | | spec.ui | string \| null | No | UI / style direction as a free-form prose string, not a structured object. | | spec.tools | string[] | Yes | Full names of the MCP tools the app calls through window.archestra. | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | id | string | Yes | | | spec | object | Yes | The persisted spec when one was given, else the base spec seeded for the model. | | spec.summary | string | Yes | One-line summary of what the app is for. | | spec.features | string[] | Yes | Concrete capabilities the app should provide. | | spec.data | string \| null | No | What the app reads/persists via the App Data Store — a free-form prose string, not a structured object. | | spec.ui | string \| null | No | UI / style direction as a free-form prose string, not a structured object. | | spec.tools | string[] | Yes | Full names of the MCP tools the app calls through window.archestra. | | capability | object | Yes | | | capability.tools | object[] | Yes | | | capability.tools[].name | string | Yes | | | capability.tools[].description | string | Yes | | | capability.sdkSummary | string | Yes | | | answers | object | No | The user's answers to the clarifying questions, if any. | | persisted | boolean | Yes | Whether a spec was persisted on the app head by this call. | list_apps Required RBAC permission: app:read Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | name | string | No | Filter by name. Each whitespace-separated word must appear in the name or description, in any order — so a remembered name matches even when its word order or punctuation differs from how the app was saved. | | labels | object[] | No | Filter by labels. AND across keys, OR within the values given for the same key. | | labels[].key | string | Yes | | | labels[].value | string | Yes | | | limit | integer | No | | | 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 apps". | | 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 | |-------|------|----------|-------------| | apps | object[] | Yes | | | apps[].id | string | Yes | | | apps[].name | string | Yes | | | apps[].description | string \| null | Yes | | | apps[].scope | "personal" \| "team" \| "org" | Yes | | | apps[].latestVersion | number | Yes | | | apps[].labels | object[] | Yes | Key-value labels for organization/categorization. | | apps[].labels[].key | string | Yes | The label key. | | apps[].labels[].value | string | Yes | The label value. | | apps[].warnings | string[] | No | Soft save-time validation warnings about the html (the save succeeded); fix them via edit_app. | list_app_versions Required RBAC permission: app:read Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | appId | string | Yes | The app id. | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | appId | string | Yes | | | latestVersion | number | Yes | | | versions | object[] | Yes | | | versions[].version | number | Yes | | | versions[].createdAt | string | Yes | | | versions[].current | boolean | Yes | | render_app Required RBAC permission: app:read Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | appId | string | Yes | The app id. | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | id | string | Yes | | | name | string | Yes | | | description | string \| null | Yes | | | scope | "personal" \| "team" \| "org" | Yes | | | latestVersion | number | Yes | | | labels | object[] | Yes | Key-value labels for organization/categorization. | | labels[].key | string | Yes | The label key. | | labels[].value | string | Yes | The label value. | | warnings | string[] | No | Soft save-time validation warnings about the html (the save succeeded); fix them via edit_app. | read_app Required RBAC permission: app:read Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | appId | string | Yes | The app id. | | version | integer | No | Specific version to read; defaults to the current head. | | offset | integer | No | Start of the read window as a 0-based character offset (a JavaScript string index / UTF-16 code unit) into the stored HTML — character-based, not line-based, since minified HTML can be one enormous line. Defaults to 0. An offset past the end returns an empty window, not an error. A window never splits a character in half: its edges shift by one unit when they would. | | limit | integer | No | Maximum number of characters to return, starting at offset. Omitted reads to the end of the document; 0 returns no content, just the size metadata. | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | id | string | Yes | | | name | string | Yes | | | scope | "personal" \| "team" \| "org" | Yes | | | version | number | Yes | | | byteSize | number | Yes | UTF-8 byte size of the full stored HTML (never the window's). | | totalChars | number | Yes | Total character length of the full stored HTML. | | offset | number | Yes | Effective 0-based character offset of the returned window (0 for a full read; clamped to the end when past it). | | hasMore | boolean | Yes | True when the document continues past the returned window. | | html | string | Yes | The stored HTML, pre-injection (no SDK/base CSS) — the requested character window when offset/limit was passed. | restore_app_version Required RBAC permission: update on the app (granted per item) Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | appId | string | Yes | The app id. | | version | integer | Yes | The historical version to restore. | | baseVersion | integer | Yes | The current head version. This prevents overwriting a newer edit that landed after the rollback was requested. | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | id | string | Yes | | | name | string | Yes | | | description | string \| null | Yes | | | scope | "personal" \| "team" \| "org" | Yes | | | latestVersion | number | Yes | | | labels | object[] | Yes | Key-value labels for organization/categorization. | | labels[].key | string | Yes | The label key. | | labels[].value | string | Yes | The label value. | | warnings | string[] | No | Soft save-time validation warnings about the html (the save succeeded); fix them via edit_app. | edit_app Required RBAC permission: update on the app (granted per item) Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | appId | string | Yes | The app id. | | baseVersion | integer | Yes | The version this edit is based on — the one named by read_app or the latest scaffold_app/edit_app result. Always report the version you actually built the edit from. When the head has moved past it (another conversation edited the app), your edit is treated as a delta from that base and merged with the newer changes; if the regions overlap, the call fails with the head's conflicting content to incorporate. | | edits | object[] | No | str_replace edits applied in order to the current HTML; the whole edit is atomic (any failure leaves the app unchanged). Pass exactly one edit mode. | | edits[].old_str | string | Yes | Exact text to replace; must occur exactly once in the current HTML (add surrounding context to disambiguate). | | edits[].new_str | string | Yes | Replacement text (may be empty to delete). | | replacementHtml | string | No | The complete new document, replacing the current HTML outright with no old_str matching — use this for a full rewrite instead of reproducing the whole document as an edit. Pass exactly one edit mode. | | replacementHtmlSource | object | No | Like replacementHtml, but the document is read server-side from a file you already saved instead of being written out here — use this when the HTML already exists as a file (assembled in the sandbox, or attached to the chat) so its bytes never have to be reproduced as tool arguments. The file must be UTF-8 text and is subject to the same size limit as any other document. Reads whatever the file holds at call time. Pass exactly one edit mode. | | replacementHtmlSource.fileId | string | Yes | Id of a saved file whose bytes become the document, as returned by download_file, save_file, or search_files. | | imageReplacements | object[] | No | Replace one or more image URLs with the most recently attached image. Pass short surrounding anchors only: the server reads the newest attachment bytes, builds the data URL, and replaces everything between the anchors. Never put attachment ids, filenames, paths, or old/new base64 in edits/tool arguments. The batch is atomic. Pass exactly one edit mode. | | imageReplacements[].before_str | string | Yes | Exact short HTML ending with the opening quote immediately before the existing image URL or data URL (for example Issue tracker

, 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 | |-------|------|----------|-------------| | projects | object[] | Yes | Projects the caller can reach. | | projects[].id | string | Yes | The project's id — pass it to get_project. | | projects[].name | string | Yes | The project's name. | | projects[].description | string \| null | Yes | The project's description. | | projects[].visibility | "organization" \| "team" \| "user" \| null | Yes | Who the project is shared with; null = owner-only. | | projects[].viewer_role | "owner" \| "shared" \| "admin" | Yes | The caller's relationship to the project. | | projects[].owner_name | string \| null | Yes | Display name of the owner. | | projects[].labels | object[] | Yes | Key/value labels assigned to the project. | | projects[].labels[].key | string | Yes | | | projects[].labels[].value | string | Yes | | | projects[].labels[].keyId | string | No | | | projects[].labels[].valueId | string | No | | | projects[].conversation_count | integer | Yes | How many chats live in the project. | | projects[].created_at | string | Yes | ISO 8601 creation timestamp. | get_project Required RBAC permission: project:read Additional access requirement: Readable only for projects the caller owns or that are shared with them. Oversight of every project (a * grant) does not extend to this tool. Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | project_id | string | Yes | Id of the project to read (from list_projects). | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | id | string | Yes | The project's id — pass it to get_project. | | name | string | Yes | The project's name. | | description | string \| null | Yes | The project's description. | | visibility | "organization" \| "team" \| "user" \| null | Yes | Who the project is shared with; null = owner-only. | | viewer_role | "owner" \| "shared" \| "admin" | Yes | The caller's relationship to the project. | | owner_name | string \| null | Yes | Display name of the owner. | | labels | object[] | Yes | Key/value labels assigned to the project. | | labels[].key | string | Yes | | | labels[].value | string | Yes | | | labels[].keyId | string | No | | | labels[].valueId | string | No | | | conversation_count | integer | Yes | How many chats live in the project. | | created_at | string | Yes | ISO 8601 creation timestamp. | | instructions | string | Yes | The project's instructions markdown; empty when never saved. Truncated when instructions_truncated is true. | | instructions_truncated | boolean | Yes | Whether instructions was cut short at the inline limit. | | files | object[] | Yes | Files the project owns. Read one with read_file, passing the same project_id and this ref. | | files[].id | string | Yes | The file's id. | | files[].ref | string | Yes | Stable reference to pass to read_file. | | files[].filename | string | Yes | The file's name. | | files[].mime_type | string | Yes | The file's MIME type. | | files[].size_bytes | integer | Yes | Size in bytes. | | apps | object[] | Yes | Apps linked into the project that you can open. Read or edit one with the app tools, passing this id. | | apps[].id | string | Yes | The app's id. | | apps[].name | string | Yes | The app's name. | | apps[].description | string \| null | Yes | The app's description. | link_app_to_project Required RBAC permission: project:read Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | project_id | string | Yes | Id of the project (from list_projects). | | app_id | string | Yes | Id of the app (from list_apps). | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | project_id | string | Yes | The project's id. | | app_id | string | Yes | The app's id. | | linked | boolean | Yes | Whether the app is now linked. | unlink_app_from_project Required RBAC permission: project:read Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | project_id | string | Yes | Id of the project (from list_projects). | | app_id | string | Yes | Id of the app (from list_apps). | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | project_id | string | Yes | The project's id. | | app_id | string | Yes | The app's id. | | linked | boolean | Yes | Whether the app is now linked. | create_schedule_trigger Required RBAC permission: project:create Additional access requirement: Requires an acting user. Omitting project_id creates a private project with the task prompt as its instructions. Repeating the same new-project task returns the existing schedule. An existing project must be accessible to the caller. Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | name | string | Yes | Name of the scheduled task. | | project_id | string | No | Existing project to schedule in. Omit to create a private project using name and message_template as its instructions. | | agent_id | string | No | Agent to run. For a new project, defaults to the current agent; for an existing project, its agent then the organization default. | | cron_expression | string | Yes | Cron expression, for example 0 9 1-5. | | timezone | string | Yes | IANA timezone, for example America/Toronto. | | message_template | string | Yes | Prompt sent to the agent on each run. | | enabled | boolean | No | Whether the schedule is enabled. Defaults to true on creation. | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | id | string | Yes | The trigger's id — pass it to get_schedule_trigger. | | name | string | Yes | The trigger's name. | | agent_id | string | Yes | Id of the agent the schedule runs. | | agent_name | string \| null | Yes | Name of that agent. | | project_id | string \| null | Yes | Project the schedule belongs to, when it is project-scoped. | | cron_expression | string | Yes | 5-part cron expression driving the schedule. | | timezone | string | Yes | IANA timezone the cron expression is read in. | | enabled | boolean | Yes | Whether the schedule is currently picked up when due. | | last_executed_at | string \| null | Yes | ISO 8601 timestamp of the last time the schedule fired, or null if it never has. Compare with run history when checking schedule activity. | | actor_user_id | string | Yes | The user the scheduled run executes as. | | actor_name | string \| null | Yes | Display name of that user. | | created_at | string | Yes | ISO 8601 creation timestamp. | | message_template | string | Yes | The prompt sent to the agent on every run. | | created | boolean | Yes | False when an identical new-project request reused an existing schedule. | update_schedule_trigger Required RBAC permission: project:update Additional access requirement: Requires a user token. Only the schedule actor or someone with organization-wide Projects Can update access can perform this action. Project membership alone permits reading. See Granular Access Control. Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | name | string | No | Name of the scheduled task. | | project_id | string | No | Project containing the scheduled task. | | agent_id | string | No | Agent to run. Defaults to the project's agent, then the organization default. | | cron_expression | string | No | Cron expression, for example 0 9 1-5. | | timezone | string | No | IANA timezone, for example America/Toronto. | | message_template | string | No | Prompt sent to the agent on each run. | | enabled | boolean | No | Whether the schedule is enabled. Defaults to true on creation. | | schedule_trigger_id | string | Yes | | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | id | string | Yes | The trigger's id — pass it to get_schedule_trigger. | | name | string | Yes | The trigger's name. | | agent_id | string | Yes | Id of the agent the schedule runs. | | agent_name | string \| null | Yes | Name of that agent. | | project_id | string \| null | Yes | Project the schedule belongs to, when it is project-scoped. | | cron_expression | string | Yes | 5-part cron expression driving the schedule. | | timezone | string | Yes | IANA timezone the cron expression is read in. | | enabled | boolean | Yes | Whether the schedule is currently picked up when due. | | last_executed_at | string \| null | Yes | ISO 8601 timestamp of the last time the schedule fired, or null if it never has. Compare with run history when checking schedule activity. | | actor_user_id | string | Yes | The user the scheduled run executes as. | | actor_name | string \| null | Yes | Display name of that user. | | created_at | string | Yes | ISO 8601 creation timestamp. | | message_template | string | Yes | The prompt sent to the agent on every run. | delete_schedule_trigger Required RBAC permission: project:delete Additional access requirement: Requires a user token. Only the schedule actor or someone with organization-wide Projects Full access access can perform this action. Project membership alone permits reading. See Granular Access Control. Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | schedule_trigger_id | string | Yes | | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | success | boolean | Yes | | list_schedule_triggers Required RBAC permission: project:read Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | project_id | string | No | Only schedules of this project. Shows every member's schedules for it, so long as the caller can access the project. | | enabled | boolean | No | Only enabled (true) or only disabled (false) schedules. | | agent_id | string | No | Only schedules that run this agent. | | include_all_users | boolean | No | Include other members' schedules. Ignored unless the caller holds organization-wide project access. | | limit | integer | No | How many rows to return, newest first (1-100, default 25). | | cursor | string | No | Pass pagination.nextCursor from the previous response to read the next page. Keep the same filters; omit for the newest page. | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | pagination | object | Yes | | | pagination.limit | integer | Yes | | | pagination.nextCursor | string \| null | Yes | | | pagination.hasNext | boolean | Yes | | | schedule_triggers | object[] | Yes | Matching schedules, newest first. | | schedule_triggers[].id | string | Yes | The trigger's id — pass it to get_schedule_trigger. | | schedule_triggers[].name | string | Yes | The trigger's name. | | schedule_triggers[].agent_id | string | Yes | Id of the agent the schedule runs. | | schedule_triggers[].agent_name | string \| null | Yes | Name of that agent. | | schedule_triggers[].project_id | string \| null | Yes | Project the schedule belongs to, when it is project-scoped. | | schedule_triggers[].cron_expression | string | Yes | 5-part cron expression driving the schedule. | | schedule_triggers[].timezone | string | Yes | IANA timezone the cron expression is read in. | | schedule_triggers[].enabled | boolean | Yes | Whether the schedule is currently picked up when due. | | schedule_triggers[].last_executed_at | string \| null | Yes | ISO 8601 timestamp of the last time the schedule fired, or null if it never has. Compare with run history when checking schedule activity. | | schedule_triggers[].actor_user_id | string | Yes | The user the scheduled run executes as. | | schedule_triggers[].actor_name | string \| null | Yes | Display name of that user. | | schedule_triggers[].created_at | string | Yes | ISO 8601 creation timestamp. | get_schedule_trigger Required RBAC permission: project:read Additional access requirement: Requires a user token. The caller must be the schedule actor, a project member, or someone with organization-wide Projects Can read access. Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | schedule_trigger_id | string | Yes | Id of the schedule to read. | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | id | string | Yes | The trigger's id — pass it to get_schedule_trigger. | | name | string | Yes | The trigger's name. | | agent_id | string | Yes | Id of the agent the schedule runs. | | agent_name | string \| null | Yes | Name of that agent. | | project_id | string \| null | Yes | Project the schedule belongs to, when it is project-scoped. | | cron_expression | string | Yes | 5-part cron expression driving the schedule. | | timezone | string | Yes | IANA timezone the cron expression is read in. | | enabled | boolean | Yes | Whether the schedule is currently picked up when due. | | last_executed_at | string \| null | Yes | ISO 8601 timestamp of the last time the schedule fired, or null if it never has. Compare with run history when checking schedule activity. | | actor_user_id | string | Yes | The user the scheduled run executes as. | | actor_name | string \| null | Yes | Display name of that user. | | created_at | string | Yes | ISO 8601 creation timestamp. | | message_template | string | Yes | The prompt sent to the agent on every run. | list_schedule_trigger_runs Required RBAC permission: project:read Additional access requirement: Requires a user token. The caller must be the schedule actor, a project member, or someone with organization-wide Projects Can read access. Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | schedule_trigger_id | string | Yes | Id of the schedule whose runs to list. | | status | "running" \| "success" \| "failed" \| "cancelled" | No | Only runs in this state. | | limit | integer | No | How many rows to return, newest first (1-100, default 25). | | cursor | string | No | Pass pagination.nextCursor from the previous response to read the next page. Keep the same filters; omit for the newest page. | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | pagination | object | Yes | | | pagination.limit | integer | Yes | | | pagination.nextCursor | string \| null | Yes | | | pagination.hasNext | boolean | Yes | | | runs | object[] | Yes | Matching runs, newest first. | | runs[].blocked_by | object \| null | Yes | Why this tick was skipped, including the blocking run and its frozen deadline. | | runs[].blocked_by.phase | "starting" \| "running" \| "stopping" | Yes | | | runs[].blocked_by.runId | string \| null | Yes | | | runs[].blocked_by.runtimeTaskId | string \| null | Yes | | | runs[].blocked_by.startedAt | string | Yes | | | runs[].blocked_by.elapsedSeconds | integer | Yes | | | runs[].blocked_by.deadline | string \| null | Yes | | | runs[].blocked_by.maximumDurationSeconds | integer \| null | Yes | | | runs[].id | string | Yes | The run's id — pass it to get_schedule_trigger_run. | | runs[].trigger_id | string | Yes | Id of the schedule this run belongs to. | | runs[].run_kind | "due" \| "manual" | Yes | due = fired by the schedule; manual = started by a person. | | runs[].status | "running" \| "success" \| "failed" \| "cancelled" | Yes | Current state of the run. | | runs[].started_at | string \| null | Yes | ISO 8601 timestamp the run started. | | runs[].completed_at | string \| null | Yes | ISO 8601 timestamp the run settled; null while still running. | | runs[].error | string \| null | Yes | Failure text when the run failed or was skipped — for example a run skipped because the previous one was still in progress. | | runs[].chat_conversation_id | string \| null | Yes | Chat conversation holding the run's transcript, when linked. | | runs[].runtime_task_id | string \| null | Yes | Agent Runtime task id, when the run executed on the runtime. | | runs[].created_at | string | Yes | ISO 8601 creation timestamp. | get_schedule_trigger_run Required RBAC permission: project:read Additional access requirement: Requires a user token. The caller must be the schedule actor, a project member, or someone with organization-wide Projects Can read access. Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | schedule_trigger_id | string | Yes | Id of the schedule the run belongs to. | | run_id | string | Yes | Id of the run to read. | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | blocked_by | object \| null | Yes | Why this tick was skipped, including the blocking run and its frozen deadline. | | blocked_by.phase | "starting" \| "running" \| "stopping" | Yes | | | blocked_by.runId | string \| null | Yes | | | blocked_by.runtimeTaskId | string \| null | Yes | | | blocked_by.startedAt | string | Yes | | | blocked_by.elapsedSeconds | integer | Yes | | | blocked_by.deadline | string \| null | Yes | | | blocked_by.maximumDurationSeconds | integer \| null | Yes | | | id | string | Yes | The run's id — pass it to get_schedule_trigger_run. | | trigger_id | string | Yes | Id of the schedule this run belongs to. | | run_kind | "due" \| "manual" | Yes | due = fired by the schedule; manual = started by a person. | | status | "running" \| "success" \| "failed" \| "cancelled" | Yes | Current state of the run. | | started_at | string \| null | Yes | ISO 8601 timestamp the run started. | | completed_at | string \| null | Yes | ISO 8601 timestamp the run settled; null while still running. | | error | string \| null | Yes | Failure text when the run failed or was skipped — for example a run skipped because the previous one was still in progress. | | chat_conversation_id | string \| null | Yes | Chat conversation holding the run's transcript, when linked. | | runtime_task_id | string \| null | Yes | Agent Runtime task id, when the run executed on the runtime. | | created_at | string | Yes | ISO 8601 creation timestamp. | get_schedule_trigger_run_transcript Required RBAC permission: project:read Additional access requirement: Requires a user token. The caller must be the schedule actor, or hold both organization-wide Projects Can read access and log:admin. Project membership or Projects read alone shows run status but not the transcript. Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | schedule_trigger_id | string | Yes | Id of the schedule the run belongs to. | | run_id | string | Yes | Id of the run to read. | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | run | object | Yes | | | run.blocked_by | object \| null | Yes | Why this tick was skipped, including the blocking run and its frozen deadline. | | run.blocked_by.phase | "starting" \| "running" \| "stopping" | Yes | | | run.blocked_by.runId | string \| null | Yes | | | run.blocked_by.runtimeTaskId | string \| null | Yes | | | run.blocked_by.startedAt | string | Yes | | | run.blocked_by.elapsedSeconds | integer | Yes | | | run.blocked_by.deadline | string \| null | Yes | | | run.blocked_by.maximumDurationSeconds | integer \| null | Yes | | | run.id | string | Yes | The run's id — pass it to get_schedule_trigger_run. | | run.trigger_id | string | Yes | Id of the schedule this run belongs to. | | run.run_kind | "due" \| "manual" | Yes | due = fired by the schedule; manual = started by a person. | | run.status | "running" \| "success" \| "failed" \| "cancelled" | Yes | Current state of the run. | | run.started_at | string \| null | Yes | ISO 8601 timestamp the run started. | | run.completed_at | string \| null | Yes | ISO 8601 timestamp the run settled; null while still running. | | run.error | string \| null | Yes | Failure text when the run failed or was skipped — for example a run skipped because the previous one was still in progress. | | run.chat_conversation_id | string \| null | Yes | Chat conversation holding the run's transcript, when linked. | | run.runtime_task_id | string \| null | Yes | Agent Runtime task id, when the run executed on the runtime. | | run.created_at | string | Yes | ISO 8601 creation timestamp. | | session_id | string | Yes | The run's session id. Pass it to list_openappa_consults or list_openappa_yells. | | source | "conversation" \| "interactions" \| "encrypted" \| "runtime" \| "pending" \| "none" | Yes | conversation = the run's chat; interactions = rebuilt from its LLM calls; encrypted = the chat is encrypted and cannot be read here; runtime = it ran on the Agent Runtime, whose output is read on its run page; pending = it finished under a minute ago with nothing recorded yet; its record may still be written, so read it again shortly; none = nothing was recorded. | | messages | object[] | Yes | The run's messages in order, with long values shortened. | | messages[].role | string | Yes | | | messages[].parts | object[] | Yes | | | messages[].parts[].type | string | Yes | text, tool, or the UI part type when it is something else. | | messages[].parts[].text | string | No | Message text, for a text part. | | messages[].parts[].tool_name | string | No | Tool called, for a tool part. | | messages[].parts[].tool_call_id | string | No | The tool call's id. | | messages[].parts[].parent_tool_call_id | string | No | For a delegated agent's call, the delegation call that started that agent. | | messages[].parts[].state | string | No | The tool call's final state. | | messages[].parts[].input | string | No | The tool call's arguments as JSON. | | messages[].parts[].output | string | No | The tool result as JSON, including any guardrails ruling. | | messages[].parts[].error_text | string | No | The tool call's error text. | | truncated | boolean | Yes | True when parts were left out to keep the result small. | enable_schedule_trigger Required RBAC permission: project:update Additional access requirement: Requires a user token. Only the schedule actor or someone with organization-wide Projects Can update access can perform this action. Project membership alone permits reading. See Granular Access Control. Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | schedule_trigger_id | string | Yes | Id of the schedule to enable. | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | id | string | Yes | The trigger's id — pass it to get_schedule_trigger. | | name | string | Yes | The trigger's name. | | agent_id | string | Yes | Id of the agent the schedule runs. | | agent_name | string \| null | Yes | Name of that agent. | | project_id | string \| null | Yes | Project the schedule belongs to, when it is project-scoped. | | cron_expression | string | Yes | 5-part cron expression driving the schedule. | | timezone | string | Yes | IANA timezone the cron expression is read in. | | enabled | boolean | Yes | Whether the schedule is currently picked up when due. | | last_executed_at | string \| null | Yes | ISO 8601 timestamp of the last time the schedule fired, or null if it never has. Compare with run history when checking schedule activity. | | actor_user_id | string | Yes | The user the scheduled run executes as. | | actor_name | string \| null | Yes | Display name of that user. | | created_at | string | Yes | ISO 8601 creation timestamp. | disable_schedule_trigger Required RBAC permission: project:update Additional access requirement: Requires a user token. Only the schedule actor or someone with organization-wide Projects Can update access can perform this action. Project membership alone permits reading. See Granular Access Control. Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | schedule_trigger_id | string | Yes | Id of the schedule to disable. | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | id | string | Yes | The trigger's id — pass it to get_schedule_trigger. | | name | string | Yes | The trigger's name. | | agent_id | string | Yes | Id of the agent the schedule runs. | | agent_name | string \| null | Yes | Name of that agent. | | project_id | string \| null | Yes | Project the schedule belongs to, when it is project-scoped. | | cron_expression | string | Yes | 5-part cron expression driving the schedule. | | timezone | string | Yes | IANA timezone the cron expression is read in. | | enabled | boolean | Yes | Whether the schedule is currently picked up when due. | | last_executed_at | string \| null | Yes | ISO 8601 timestamp of the last time the schedule fired, or null if it never has. Compare with run history when checking schedule activity. | | actor_user_id | string | Yes | The user the scheduled run executes as. | | actor_name | string \| null | Yes | Display name of that user. | | created_at | string | Yes | ISO 8601 creation timestamp. | run_schedule_trigger_now Required RBAC permission: project:create Additional access requirement: Requires a user token. Only the schedule actor or someone with organization-wide Projects Can use access can perform this action. Project membership alone permits reading. See Granular Access Control. Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | schedule_trigger_id | string | Yes | Id of the schedule to run. | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | blocked_by | object \| null | Yes | Why this tick was skipped, including the blocking run and its frozen deadline. | | blocked_by.phase | "starting" \| "running" \| "stopping" | Yes | | | blocked_by.runId | string \| null | Yes | | | blocked_by.runtimeTaskId | string \| null | Yes | | | blocked_by.startedAt | string | Yes | | | blocked_by.elapsedSeconds | integer | Yes | | | blocked_by.deadline | string \| null | Yes | | | blocked_by.maximumDurationSeconds | integer \| null | Yes | | | id | string | Yes | The run's id — pass it to get_schedule_trigger_run. | | trigger_id | string | Yes | Id of the schedule this run belongs to. | | run_kind | "due" \| "manual" | Yes | due = fired by the schedule; manual = started by a person. | | status | "running" \| "success" \| "failed" \| "cancelled" | Yes | Current state of the run. | | started_at | string \| null | Yes | ISO 8601 timestamp the run started. | | completed_at | string \| null | Yes | ISO 8601 timestamp the run settled; null while still running. | | error | string \| null | Yes | Failure text when the run failed or was skipped — for example a run skipped because the previous one was still in progress. | | chat_conversation_id | string \| null | Yes | Chat conversation holding the run's transcript, when linked. | | runtime_task_id | string \| null | Yes | Agent Runtime task id, when the run executed on the runtime. | | created_at | string | Yes | ISO 8601 creation timestamp. | Agent Runtime | Tool | Description | Permission | |------|-------------|--------------------------| | delete_workspace | Permanently delete a retained runtime workspace and all of its files. | agent:read | | read_workspace_file | Read a file from your Agent Runtime's retained workspace using its run_id. | agent:read | | transfer_workspace_file | Copy a file between this machine and a Remote Agent's workspace without reading it. | agent:read | | write_workspace_file | Create a file in your Agent Runtime's retained workspace using its run_id. | agent:read | | start_agent_run | Start a background run on an Agent that has Agent Runtime. | agent:read | | get_agent_run | Read a run's state, the result it has handed back so far, and whether it accepts a follow-up. | agent:read | | list_agent_runs | List recent runs on one or more accessible Agents, newest first. | agent:read | | steer_agent_run | 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... | agent:read | | cancel_agent_run | Stop an active run. | agent:read | | post_agent_run_message | Post a brief update to the Slack thread an active Agent Runtime run reports to. | agent:read | | post_agent_run_file | 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). | agent:read | | transfer_credential | Give a Remote Agent a credential, so a handed-over task can use the CLI authentication the local session was using. | credential:create | delete_workspace Required RBAC permission: agent:read Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | run_id | string | Yes | | | confirm_delete | true | Yes | | read_workspace_file Required RBAC permission: agent:read Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | run_id | string | Yes | | | path | string | Yes | | | encoding | "utf8" \| "base64" | No | | transfer_workspace_file Required RBAC permission: agent:read Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | run_id | string | Yes | From start_agent_run or list_agent_runs. | | direction | "download" \| "upload" | Yes | download reads from the workspace; upload writes to it. | | path | string | Yes | Workspace-relative path, for example reports/summary.md. | | local_path | string | Yes | Absolute path on this machine, used to build the command. | | size | integer | No | Upload only: the local file's size in bytes. | | sha256 | string | No | Upload only: the local file's sha256, as hex. | write_workspace_file Required RBAC permission: agent:read Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | run_id | string | Yes | | | path | string | Yes | | | content | string | Yes | | | encoding | "utf8" \| "base64" | No | | | overwrite | boolean | No | | start_agent_run Required RBAC permission: agent:read Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | agent_id | string | Yes | The agent to do the work. | | 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 | | 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. | | run.state | string | Yes | submitted \| working \| input-required \| completed \| canceled \| failed | | run.agent_id | string \| null | Yes | The agent doing the work. | | run.status_reason | string \| null | Yes | Why the run is in its state, when there is something to say. | | run.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. | | run.failure.code | string | Yes | | | run.failure.retriable | boolean | Yes | | | run.created_at | string | Yes | ISO 8601. | | run.state_changed_at | string | Yes | ISO 8601 of the last transition. | | run_url | string | Yes | Open the run and its workspace in the browser. | | next_step | string | Yes | What to do now. | get_agent_run Required RBAC permission: agent:read Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | run_id | string | Yes | From start_agent_run or list_agent_runs. | 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. | | run.state | string | Yes | submitted \| working \| input-required \| completed \| canceled \| failed | | run.agent_id | string \| null | Yes | The agent doing the work. | | run.status_reason | string \| null | Yes | Why the run is in its state, when there is something to say. | | run.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. | | run.failure.code | string | Yes | | | run.failure.retriable | boolean | Yes | | | run.created_at | string | Yes | ISO 8601. | | run.state_changed_at | string | Yes | ISO 8601 of the last transition. | | run_url | string \| null | Yes | | | requests | object[] | Yes | The run's original request and, when different, the current turn's request. Use this context to interpret short follow-ups. | | requests[].text | string | Yes | | | requests[].truncated | boolean | Yes | | | output | string | Yes | The run's response artifact so far (tail, capped). | | output_truncated | boolean | Yes | | | workspace | object \| null | Yes | The owner's retained workspace, independent of the run's terminal state. | | workspace.state | "active" \| "idle" \| "suspending" \| "suspended" \| "resuming" \| "deleting" \| "deleted" | Yes | | | workspace.retained_until | string | Yes | | | workspace.can_continue | boolean | Yes | Whether steer_agent_run can accept a follow-up in this workspace, including while work is running. | | workspace.continuation_error | string \| null | Yes | Why this workspace cannot accept steering, or null when available. | | workspace.connection | object \| null | Yes | | | workspace.connection.hostname | string | Yes | | | workspace.connection.shellCommand | string | Yes | | | session | object \| null | Yes | The live container session, when the run uses Agent Runtime. | | session.attachable | boolean | Yes | Whether a live container is carrying the run right now. | | session.started_at | string \| null | Yes | | list_agent_runs Required RBAC permission: agent:read Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | agent_ids | string[] | Yes | | | mine_only | boolean | No | Only runs you started. | | state | "submitted" \| "working" \| "input-required" \| "completed" \| "canceled" \| "failed" | No | Only runs in this state. | | failed_since | string | No | 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. | | runs[].state | string | Yes | submitted \| working \| input-required \| completed \| canceled \| failed | | runs[].agent_id | string \| null | No | The agent doing the work. | | 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; URL-encode it as one path segment. Null when no readable logged session is available. This is not a task ID or runtime handle. | | 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. | | runs[].agent | object | No | | | runs[].requester | object | No | | | runs[].run_url | string | No | | | runs[].thread | object \| null | No | | | summary | object | Yes | | | summary.total | integer | Yes | | | summary.active | integer | Yes | | | summary.by_state | object | Yes | | steer_agent_run Required RBAC permission: agent:read Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | run_id | string | Yes | | | message | string | Yes | | cancel_agent_run Required RBAC permission: agent:read Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | run_id | string | Yes | | post_agent_run_message Required RBAC permission: agent:read Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | task_id | string | Yes | | | message | string | Yes | | post_agent_run_file Required RBAC permission: agent:read Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | task_id | string | Yes | | | path | string | No | The file in the run's own workspace, relative to /home/node/workspace (for example demo/demo.mp4) or absolute under it. | | filename | string | No | Name shown in the thread. Defaults to the last part of path; required with content_base64. | | content_base64 | string | No | The file's bytes, base64-encoded, when there is no path. | | comment | string | No | | transfer_credential Required RBAC permission: credential:create Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | agent_id | string | Yes | The Agent to give the credential to. | | 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. | 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. | | 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. | Agents | Tool | Description | Permission | |------|-------------|--------------------------| | create_agent | Create a new agent with the specified name, optional description, labels, prompts, icon emoji, model, explicit tool assignments, and sub-agent delegations. | agent:create | | get_agent | Get a specific agent by ID or name. | agent:read | | list_agents | List agents with optional filtering by name, provider key, or how the caller reaches them (access). | agent:read | | edit_agent | Edit an existing agent. | update on the agent (granted per item) | | list_llm_models | List the provider API keys the caller can use and the models linked to each. | llmModel:read | | list_hooks | List an agent's lifecycle hooks. | agent:read | | create_hook | Create a lifecycle hook on an agent. | update on the agent (granted per item) | | update_hook | Update an existing lifecycle hook: its event, file name, script content, Python requirements, or enabled state. | update on the agent (granted per item) | | delete_hook | Delete a lifecycle hook by ID. | update on the agent (granted per item) | create_agent Required RBAC permission: agent:create Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | initialGrants | object[] | No | | | initialGrants[].subject | object | Yes | | | initialGrants[].subject.type | "user" \| "team" \| "serviceAccount" \| "role" \| "organization" | Yes | | | initialGrants[].subject.id | string \| "*" | Yes | | | initialGrants[].actions | string[] | Yes | | | name | string | Yes | Name for the new resource. | | labels | object[] | No | 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. | | runtime.backend | "kubernetes" | No | | | runtime.steerMode | "pipe" \| "tmux_keys" | No | | | runtime.privileged | boolean | No | | | runtime.resources | object \| null | No | | | runtime.ports | integer[] | No | | | runtime.environment | object[] \| null | No | | | runtime.credentials | object[] \| null | No | | | runtime.allowAgentSuppliedCredentialValues | boolean | No | | | runtime.claudeCode | object | No | | | runtime.ttlHours | integer \| null | No | | | runtime.maxCostUsd | integer \| null | No | | | runtime.idleTimeoutMinutes | integer \| null | No | | | runtime.template | "claude-code" \| "codex" \| "opencode" \| "hermes" \| "openclaw" \| "grok" \| "kimi" \| "copilot" | No | 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 | | | llmApiKeyId | string | No | Provider API key the agent uses. Set together with modelId. Use list_llm_models to find both. | | modelId | string | No | Model the agent uses: the model's id from list_llm_models, not its provider name. Set together with llmApiKeyId. | | fastModelId | string | No | Optional faster model on the same llmApiKeyId, used when the agent forks itself with tier fast. Omit to use the provider default. | | smartModelId | string | No | Optional stronger model on the same llmApiKeyId, used when the agent forks itself with tier smart. Omit to use the provider default. | get_agent Required RBAC permission: agent:read Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | string | No | The ID of the agent to fetch. Prefer the ID when you already have it. | | name | string | No | The exact name of the agent to fetch when you do not already have the ID. | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | id | string | Yes | The resource ID. | | name | string | Yes | The resource name. | | description | string \| null | Yes | The resource description, if any. | | icon | string \| null | Yes | The emoji icon, if configured. | | scope | "personal" \| "team" \| "org" | Yes | The visibility scope. | | toolExposureMode | "full" \| "search_and_run_only" | Yes | How tools are loaded for MCP clients and models. | | accessAllTools | boolean | Yes | Whether search_tools/run_tool may dynamically access every tool the calling user can access. | | accessAllSubagents | boolean | Yes | Whether the agent may delegate to every internal agent the calling user can access. | | agentType | "agent" \| "llm_proxy" \| "mcp_gateway" \| "profile" | Yes | The resource type. | | systemPrompt | string \| null | No | | | teams | object[] | Yes | The teams attached to it. | | teams[].id | string | Yes | The team ID. | | teams[].name | string | Yes | The team name. | | labels | object[] | Yes | Assigned labels. | | labels[].key | string | Yes | The label key. | | labels[].value | string | Yes | The label value. | | tools | object[] | Yes | Assigned tools. | | tools[].id | string | Yes | The assigned tool ID. | | tools[].name | string | Yes | The tool name. | | tools[].description | string \| null | Yes | The tool description, if any. | | tools[].catalogId | string \| null | Yes | The MCP catalog ID the tool comes from, if any. | | knowledgeBaseIds | string[] | Yes | Assigned knowledge base IDs. | | connectorIds | string[] | Yes | Assigned knowledge connector IDs. | | suggestedPrompts | object[] | Yes | Configured suggested prompts. | | suggestedPrompts[].summaryTitle | string | Yes | The short title shown in the chat UI. | | suggestedPrompts[].prompt | string | Yes | The suggested prompt text. | | runtime | object \| null | No | The Agent Runtime container this agent runs in, or null for the built-in chat harness. | | runtime.image | string | Yes | | | runtime.command | string[] \| null | Yes | | | runtime.inferenceProtocol | "openai_responses" \| "openai_chat" \| "anthropic" | Yes | | | runtime.backend | "kubernetes" | Yes | | | runtime.steerMode | "pipe" \| "tmux_keys" | Yes | | | runtime.privileged | boolean | Yes | | | runtime.resources | object \| null | Yes | | | runtime.resources.cpuRequest | string | No | | | runtime.resources.memoryRequest | string | No | | | runtime.resources.cpuLimit | string | No | | | runtime.resources.memoryLimit | string | No | | | runtime.ports | integer[] | No | | | runtime.environment | object[] \| null | Yes | | | runtime.environment[].key | string | Yes | | | runtime.environment[].value | string | Yes | | | runtime.credentials | object[] \| null | Yes | | | runtime.credentials[].key | string | Yes | | | runtime.credentials[].scope | "shared" \| "per_user" | Yes | | | runtime.credentials[].credentialId | string | No | | | runtime.credentials[].label | string | Yes | | | runtime.credentials[].description | string | No | | | runtime.credentials[].required | boolean | Yes | | | runtime.allowAgentSuppliedCredentialValues | boolean | No | | | runtime.claudeCode | object | No | | | runtime.claudeCode.authentication | "provider" \| "subscription" | Yes | | | runtime.claudeCode.model | string | No | | | runtime.ttlHours | integer \| null | Yes | | | runtime.maxCostUsd | integer \| null | No | | | runtime.idleTimeoutMinutes | integer \| null | Yes | | | llmApiKeyId | string \| null | No | The pinned provider API key ID, or null for the default. | | modelId | string \| null | No | The pinned model ID, or null for the default. | | fastModelId | string \| null | No | The pinned fast-tier model ID, or null for the default. | | smartModelId | string \| null | No | The pinned smart-tier model ID, or null for the default. | | skillsEnabled | boolean | No | Present for an internal agent when the current user has skill:read; whether load_skill is executable for it. | | skillsNotice | string | No | Trust boundary for the catalog-supplied skill names and descriptions in skills. | | skills | object[] | No | Present for an internal agent when the current user has skill:read; caller-relative skills it can activate. | | skills[].reference | object | Yes | Stable source identity: native uses skillId, external_mcp uses mcpServerId and uri, and plugin uses pluginId and skillPath. | | skills[].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. | | skills[].reference.skillId | string | When source="native" | The skill-library skill ID. | | skills[].reference.mcpServerId | string | When source="external_mcp" | The MCP server installation ID. | | skills[].reference.uri | string | When source="external_mcp" | The skill resource URI. | | skills[].reference.pluginId | string | When source="plugin" | The plugin ID. | | skills[].reference.skillPath | string | When source="plugin" | The skill root inside the plugin. | | skills[].name | string | Yes | The declared, human-facing skill name. | | skills[].activationName | string | Yes | The exact name to pass to load_skill. | | skills[].description | string | Yes | The skill description. | | skills[].scope | "personal" \| "team" \| "org" | Yes | The visibility scope through which the skill is shared. | | skills[].providerName | string \| null | Yes | Plugin or MCP server name; null for a skill-library entry. | list_agents Required RBAC permission: agent:read Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | providerApiKeyId | string \| "organization-default" | No | 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. | | 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. | | fastModelId | string \| null | No | Optional faster model on the same llmApiKeyId, used when the agent forks itself with tier fast. Omit to use the provider default. Pass null to clear. | | smartModelId | string \| null | No | Optional stronger model on the same llmApiKeyId, used when the agent forks itself with tier smart. Omit to use the provider default. Pass null to clear. | list_llm_models Required RBAC permission: llmModel:read Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | provider | "openai" \| "gemini" \| "anthropic" \| "bedrock" \| "cohere" \| "cerebras" \| "mistral" \| "perplexity" \| "groq" \| "xai" \| "openrouter" \| "vllm" \| "ollama" \| "ollama-native" \| "zhipuai" \| "deepseek" \| "minimax" \| "kimi" \| "kimi-code" \| "azure" \| "github-copilot" \| "microsoft-365-copilot" \| "archestra" \| "voyage" \| "jev" | No | Only list keys for this provider. | | query | string | No | Only list models whose name contains this text. | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | apiKeys | object[] | Yes | | | apiKeys[].id | string | Yes | Pass as llmApiKeyId. | | apiKeys[].name | string | Yes | The key's display name. | | apiKeys[].provider | string | Yes | The key's LLM provider. | | apiKeys[].models | object[] | Yes | | | apiKeys[].models[].id | string | Yes | Pass as modelId. | | apiKeys[].models[].name | string | Yes | The provider's model name. | | apiKeys[].omittedModelCount | number | Yes | Linked models left out after the first 100. Narrow with query to see them. | list_hooks Required RBAC permission: agent:read 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. Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | agent_id | string | Yes | The ID of the agent whose hooks to list. | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | hooks | object[] | Yes | | | hooks[].id | string | Yes | The hook ID. | | hooks[].agentId | string | Yes | The agent the hook belongs to. | | hooks[].event | "session_start" \| "pre_tool_use" \| "post_tool_use" | Yes | The lifecycle event the hook fires on. | | hooks[].fileName | string | Yes | 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. Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | agent_id | string | Yes | The ID of the agent to add the hook to. | | event | "session_start" \| "pre_tool_use" \| "post_tool_use" | Yes | The lifecycle event the hook fires on: session_start, pre_tool_use, or post_tool_use. | | file_name | string | Yes | Plain script file name ending in .py or .sh, e.g. check.py. Unique per (agent, event); hooks on the same event run in file-name order. | | content | string | Yes | The script content. It receives the JSON payload on stdin. | | requirements | string[] | No | Optional Python dependencies (pip requirement strings) installed before a .py hook runs. | | enabled | boolean | No | Whether the hook fires. Defaults to true. | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | hook | object | Yes | | | hook.id | string | Yes | The hook ID. | | hook.agentId | string | Yes | The agent the hook belongs to. | | hook.event | "session_start" \| "pre_tool_use" \| "post_tool_use" | Yes | The lifecycle event the hook fires on. | | hook.fileName | string | Yes | 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. Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | string | Yes | The ID of the hook to update. | | event | "session_start" \| "pre_tool_use" \| "post_tool_use" | No | Optional new lifecycle event. | | file_name | string | No | Optional new script file name ending in .py or .sh. | | content | string | No | Optional new script content. | | requirements | string[] | No | Optional replacement list of Python dependencies. | | enabled | boolean | No | Optionally enable or disable the hook. | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | hook | object | Yes | | | hook.id | string | Yes | The hook ID. | | hook.agentId | string | Yes | The agent the hook belongs to. | | hook.event | "session_start" \| "pre_tool_use" \| "post_tool_use" | Yes | The lifecycle event the hook fires on. | | hook.fileName | string | Yes | 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. Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | string | Yes | The ID of the hook to delete. | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | success | true | Yes | | | id | string | Yes | | Knowledge Management | Tool | Description | Permission | |------|-------------|--------------------------| | query_knowledge_sources | Search the organization's indexed knowledge — documents, files, images, photos, and records synced from its connected sources. | knowledgeSource:query | | create_knowledge_base | Create a new knowledge base for organizing knowledge connectors. | knowledgeSource:create | | get_knowledge_bases | List all knowledge bases in the organization. | knowledgeSource:read | | get_knowledge_base | Get details of a specific knowledge base by ID. | knowledgeSource:read | | update_knowledge_base | Update an existing knowledge base. | knowledgeSource:update | | delete_knowledge_base | Delete a knowledge base by ID. | knowledgeSource:delete | | create_knowledge_connector | Create a new knowledge connector for ingesting data from external sources. | knowledgeSource:create | | get_knowledge_connectors | List all knowledge connectors in the organization. | knowledgeSource:read | | get_knowledge_connector | Get details of a specific knowledge connector by ID. | knowledgeSource:read | | update_knowledge_connector | Update an existing knowledge connector. | knowledgeSource:update | | delete_knowledge_connector | Delete a knowledge connector by ID. | knowledgeSource:delete | | assign_knowledge_connector_to_knowledge_base | Assign a knowledge connector to a knowledge base. | knowledgeSource:update | | unassign_knowledge_connector_from_knowledge_base | Remove a knowledge connector from a knowledge base. | knowledgeSource:update | | assign_knowledge_base_to_agent | Assign a knowledge base to an agent. | knowledgeSource:update | | unassign_knowledge_base_from_agent | Remove a knowledge base from an agent. | knowledgeSource:update | | assign_knowledge_connector_to_agent | Directly assign a knowledge connector to an agent (bypassing knowledge base). | knowledgeSource:update | | unassign_knowledge_connector_from_agent | Remove a directly-assigned knowledge connector from an agent. | knowledgeSource:update | query_knowledge_sources Required RBAC permission: knowledgeSource:query Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | query | string | Yes | The user's original query, passed verbatim without rephrasing or expansion. | | documentFilter | object | No | Optional. Narrows the search to a subset of the indexed documents by their source metadata — for example {"spaceKey": "DEV"} or {"labels": ["release-2.0"]}. Keys are ANDed; a list of values for one key is ORed. Matches both single values and list-valued metadata. Only use this when the user's request explicitly names a subset to search; do NOT infer one from the topic of the question, and do NOT guess key or value names. If a filter matches nothing, the response lists the values that actually exist so the call can be retried with a real one. | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | results | any[] | Yes | Retrieved knowledge results. | | totalChunks | number | Yes | The number of result chunks returned. | | citationInstruction | string | No | How to cite these results: back each claim with a verbatim quote tagged with the source chunk's ref. | | filterDiagnostic | string | No | Present only when documentFilter matched no documents. Names the values that do exist for the keys that were filtered on, so the search can be retried. | create_knowledge_base Required RBAC permission: knowledgeSource:create Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | initialGrants | object[] | No | | | initialGrants[].subject | object | Yes | | | initialGrants[].subject.type | "user" \| "team" \| "serviceAccount" \| "role" \| "organization" | Yes | | | initialGrants[].subject.id | string \| "*" | Yes | | | initialGrants[].actions | string[] | Yes | | | name | string | Yes | Name of the knowledge base. | | description | string \| null | No | Description of the knowledge base. | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | knowledgeBase | object | Yes | The requested knowledge base. | | knowledgeBase.id | string | Yes | The knowledge base ID. | | knowledgeBase.organizationId | string | Yes | The organization ID. | | knowledgeBase.name | string | Yes | The knowledge base name. | | knowledgeBase.description | string \| null | Yes | The knowledge base description, if any. | | knowledgeBase.status | string | Yes | The knowledge base status. | get_knowledge_bases Required RBAC permission: knowledgeSource:read Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | 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 knowledge bases". | | 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 | |-------|------|----------|-------------| | knowledgeBases | object[] | Yes | Knowledge bases in the organization. | | knowledgeBases[].id | string | Yes | The knowledge base ID. | | knowledgeBases[].organizationId | string | Yes | The organization ID. | | knowledgeBases[].name | string | Yes | The knowledge base name. | | knowledgeBases[].description | string \| null | Yes | The knowledge base description, if any. | | knowledgeBases[].status | string | Yes | The knowledge base status. | get_knowledge_base Required RBAC permission: knowledgeSource:read Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | string | Yes | Knowledge base ID. | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | knowledgeBase | object | Yes | The requested knowledge base. | | knowledgeBase.id | string | Yes | The knowledge base ID. | | knowledgeBase.organizationId | string | Yes | The organization ID. | | knowledgeBase.name | string | Yes | The knowledge base name. | | knowledgeBase.description | string \| null | Yes | The knowledge base description, if any. | | knowledgeBase.status | string | Yes | The knowledge base status. | update_knowledge_base Required RBAC permission: knowledgeSource:update Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | string | Yes | Knowledge base ID. | | name | string | No | New knowledge base name. | | description | string \| null | No | New knowledge base description. | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | knowledgeBase | object | Yes | The requested knowledge base. | | knowledgeBase.id | string | Yes | The knowledge base ID. | | knowledgeBase.organizationId | string | Yes | The organization ID. | | knowledgeBase.name | string | Yes | The knowledge base name. | | knowledgeBase.description | string \| null | Yes | The knowledge base description, if any. | | knowledgeBase.status | string | Yes | The knowledge base status. | delete_knowledge_base Required RBAC permission: knowledgeSource:delete Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | string | Yes | Knowledge base ID. | create_knowledge_connector Required RBAC permission: knowledgeSource:create Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | initialGrants | object[] | No | | | initialGrants[].subject | object | Yes | | | initialGrants[].subject.type | "user" \| "team" \| "serviceAccount" \| "role" \| "organization" | Yes | | | initialGrants[].subject.id | string \| "*" | Yes | | | initialGrants[].actions | string[] | Yes | | | name | string | Yes | Name of the knowledge connector. | | connector_type | string | Yes | Type of the knowledge connector (for example jira, confluence, or google_drive). | | config | object | Yes | Provider-specific configuration object. | | description | string \| null | No | Description of the knowledge connector. | | sync_permissions_from_source | boolean | No | Mirror each document's access control from the source, so a query only returns what the caller could open there. Requires an enterprise license and a connector type that supports it. | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | knowledgeConnector | object | Yes | The requested knowledge connector. | | knowledgeConnector.id | string | Yes | The knowledge connector ID. | | knowledgeConnector.organizationId | string | Yes | The organization ID. | | knowledgeConnector.knowledgeBaseId | string \| null | No | | | knowledgeConnector.name | string | Yes | The connector name. | | knowledgeConnector.connectorType | string | Yes | The connector type. | | knowledgeConnector.description | string \| null | Yes | The connector description, if any. | | knowledgeConnector.enabled | boolean | No | | | knowledgeConnector.config | any | Yes | The provider-specific connector configuration. | get_knowledge_connectors Required RBAC permission: knowledgeSource:read This tool takes no arguments. Output | Field | Type | Required | Description | |-------|------|----------|-------------| | knowledgeConnectors | object[] | Yes | Knowledge connectors in the organization. | | knowledgeConnectors[].id | string | Yes | The knowledge connector ID. | | knowledgeConnectors[].organizationId | string | Yes | The organization ID. | | knowledgeConnectors[].knowledgeBaseId | string \| null | No | | | knowledgeConnectors[].name | string | Yes | The connector name. | | knowledgeConnectors[].connectorType | string | Yes | The connector type. | | knowledgeConnectors[].description | string \| null | Yes | The connector description, if any. | | knowledgeConnectors[].enabled | boolean | No | | | knowledgeConnectors[].config | any | Yes | The provider-specific connector configuration. | get_knowledge_connector Required RBAC permission: knowledgeSource:read Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | string | Yes | Knowledge connector ID. | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | knowledgeConnector | object | Yes | The requested knowledge connector. | | knowledgeConnector.id | string | Yes | The knowledge connector ID. | | knowledgeConnector.organizationId | string | Yes | The organization ID. | | knowledgeConnector.knowledgeBaseId | string \| null | No | | | knowledgeConnector.name | string | Yes | The connector name. | | knowledgeConnector.connectorType | string | Yes | The connector type. | | knowledgeConnector.description | string \| null | Yes | The connector description, if any. | | knowledgeConnector.enabled | boolean | No | | | knowledgeConnector.config | any | Yes | The provider-specific connector configuration. | update_knowledge_connector Required RBAC permission: knowledgeSource:update Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | string | Yes | Knowledge connector ID. | | name | string | No | New connector name. | | description | string \| null | No | New connector description. | | enabled | boolean | No | Whether the connector is enabled. | | visibility | "org-wide" \| "team-scoped" \| "auto-sync-permissions" | No | Updated visibility for the connector. | | team_ids | string[] | No | Updated team IDs for a team-scoped connector. | | config | object | No | Updated connector configuration (provider-specific settings). | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | knowledgeConnector | object | Yes | The requested knowledge connector. | | knowledgeConnector.id | string | Yes | The knowledge connector ID. | | knowledgeConnector.organizationId | string | Yes | The organization ID. | | knowledgeConnector.knowledgeBaseId | string \| null | No | | | knowledgeConnector.name | string | Yes | The connector name. | | knowledgeConnector.connectorType | string | Yes | The connector type. | | knowledgeConnector.description | string \| null | Yes | The connector description, if any. | | knowledgeConnector.enabled | boolean | No | | | knowledgeConnector.config | any | Yes | The provider-specific connector configuration. | delete_knowledge_connector Required RBAC permission: knowledgeSource:delete Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | string | Yes | Knowledge connector ID. | assign_knowledge_connector_to_knowledge_base Required RBAC permission: knowledgeSource:update Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | connector_id | string | Yes | Knowledge connector ID. | | knowledge_base_id | string | Yes | Knowledge base ID. | unassign_knowledge_connector_from_knowledge_base Required RBAC permission: knowledgeSource:update Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | connector_id | string | Yes | Knowledge connector ID. | | knowledge_base_id | string | Yes | Knowledge base ID. | assign_knowledge_base_to_agent Required RBAC permission: knowledgeSource:update Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | knowledge_base_id | string | Yes | Knowledge base ID. | | agent_id | string | Yes | Agent ID. | unassign_knowledge_base_from_agent Required RBAC permission: knowledgeSource:update Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | knowledge_base_id | string | Yes | Knowledge base ID. | | agent_id | string | Yes | Agent ID. | assign_knowledge_connector_to_agent Required RBAC permission: knowledgeSource:update Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | connector_id | string | Yes | Knowledge connector ID. | | agent_id | string | Yes | Agent ID. | unassign_knowledge_connector_from_agent Required RBAC permission: knowledgeSource:update Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | connector_id | string | Yes | Knowledge connector ID. | | agent_id | string | Yes | Agent ID. | MCP Servers | Tool | Description | Permission | |------|-------------|--------------------------| | search_private_mcp_registry | Search the private MCP registry for available MCP servers. | mcpRegistry:read | | get_mcp_servers | List all MCP servers from the catalog. | mcpRegistry:read | | get_mcp_server_tools | Get all tools available for a specific MCP server by its catalog ID (from get_mcp_servers). | mcpRegistry:read | | edit_mcp_description | Edit an MCP server's display information and metadata. | update on the MCP registry entry (granted per item) | | edit_mcp_config | Edit an MCP server's technical configuration. | update on the MCP registry entry (granted per item) | | create_mcp_server | Create a new MCP server in the private registry. | mcpRegistry:create | | deploy_mcp_server | Deploy (install) an MCP server from the catalog. | update on the MCP registry entry (granted per item) | | list_mcp_server_deployments | List deployed (installed) MCP server instances the current user can read. | mcpRegistry:read | | get_mcp_server_logs | Get recent container logs from a deployed local (K8s) MCP server. | mcpRegistry:read | | reload_mcp_server_tools | Re-discover a deployed MCP server's tools from the live server and refresh Archestra's tool catalog for it — picks up added, removed, and changed tools (names, descriptions, and input schemas) with... | mcpServerInstallation:create | search_private_mcp_registry Required RBAC permission: mcpRegistry:read Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | query | string | No | Optional search query to filter MCP servers by name or description. | | 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 MCP servers". | | 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 | |-------|------|----------|-------------| | items | object[] | Yes | Catalog items matching the search. | | items[].id | string | Yes | The catalog item ID. | | items[].name | string | Yes | The MCP server name. | | items[].version | string \| null | Yes | The version, if provided. | | items[].description | string \| null | Yes | The server description, if any. | | items[].serverType | "local" \| "remote" \| "builtin" \| "app" | Yes | Server type: local, remote, builtin, or app (user-generated App). | | items[].serverUrl | string \| null | Yes | The remote server URL, if applicable. | | items[].repository | string \| null | Yes | The repository URL, if available. | get_mcp_servers Required RBAC permission: mcpRegistry:read Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | 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 MCP servers". | | 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 | |-------|------|----------|-------------| | items | object[] | Yes | Available MCP servers. | | items[].id | string | Yes | The catalog item ID. | | items[].name | string | Yes | The MCP server name. | | items[].icon | string \| null | Yes | The emoji icon, if any. | | items[].description | string \| null | Yes | The server description, if any. | | items[].scope | "personal" \| "team" \| "org" | No | The visibility scope of the server. | | items[].teams | object[] | Yes | Teams attached to a team-scoped server. | | items[].teams[].id | string | Yes | The team ID. | | items[].teams[].name | string | Yes | The team name. | get_mcp_server_tools Required RBAC permission: mcpRegistry:read Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | mcpServerId | string | Yes | The catalog ID of the MCP server. | | view | "full" \| "picker" | No | Picker metadata excludes parameter bodies and assigned-agent lists; defaults to full. | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | tools | object[] | Yes | Tools exposed by the selected MCP server. | | tools[].id | string | Yes | The tool ID. | | tools[].name | string | Yes | The tool name. | | tools[].description | string \| null | No | The tool description, if any. | | tools[].catalogId | string \| null | No | The MCP catalog ID this tool belongs to. | edit_mcp_description Required RBAC permission: update on the MCP registry entry (granted per item) Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | string | Yes | The catalog ID of the MCP server to edit. Use get_mcp_servers to look it up by name. | | name | string | No | Display name for the MCP server. | | description | string \| null | No | Description of the MCP server. | | icon | string \| null | No | Emoji icon for the MCP server. | | docsUrl | string \| null | No | Documentation URL. | | repository | string \| null | No | Source code repository URL. | | version | string \| null | No | Version string. | | instructions | string \| null | No | Setup or usage instructions. | | labels | object[] | No | Key-value labels for organization/categorization. | | labels[].key | string | Yes | Label key. | | labels[].value | string | Yes | Label value. | edit_mcp_config Required RBAC permission: update on the MCP registry entry (granted per item) Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | string | Yes | The catalog ID of the MCP server to edit. Use get_mcp_servers to look it up by name. | | serverType | "local" \| "remote" \| "builtin" | No | Server type: local, remote, or builtin. | | serverUrl | string \| null | No | [Remote] The URL of the remote MCP server. | | requiresAuth | boolean | No | [Remote] Whether the server requires authentication. | | authDescription | string \| null | No | [Remote] How to set up authentication. | | authFields | object[] | No | [Remote] Authentication field definitions. | | authFields[].name | string | Yes | Auth field name. | | authFields[].label | string | Yes | Human-readable auth field label. | | authFields[].type | "header" \| "query" \| "cookie" | Yes | Where to send this auth field. | | authFields[].secret | boolean | Yes | Whether this field contains secret data. | | oauthConfig | object | No | [Remote] OAuth configuration for the server. | | command | string | No | [Local] Command to run (for example npx, uvx, or node). | | arguments | string[] | No | [Local] Command-line arguments. | | environment | object[] | No | [Local] Environment variables for the server process. | | environment[].key | string | Yes | Environment variable name. | | environment[].type | "plain_text" \| "secret" \| "boolean" \| "number" | Yes | Environment variable value type. | | environment[].value | string | No | Literal environment variable value. | | environment[].promptOnInstallation | boolean | Yes | Whether to prompt for this value during installation. | | environment[].required | boolean | No | Whether the value is required. | | environment[].description | string | No | Description shown to users. | | environment[].default | any | No | Default value. | | environment[].mounted | boolean | No | For secret values, mount as a file instead of an env var. | | envFrom | object[] | No | [Local] Import env vars from Kubernetes Secrets or ConfigMaps. | | envFrom[].type | "secret" \| "configMap" | Yes | Import source type. | | envFrom[].name | string | Yes | Secret or ConfigMap name. | | envFrom[].prefix | string | No | Optional environment variable prefix. | | dockerImage | string | No | [Local] Custom Docker image. | | serviceAccount | string | No | [Local] Kubernetes ServiceAccount name. | | transportType | "stdio" \| "streamable-http" | No | [Local] Transport type. Omit it for remote servers: streamable-http is ignored and stdio is rejected. | | httpPort | number | No | [Local] HTTP port for streamable-http transport. | | httpPath | string | No | [Local] HTTP path for streamable-http transport. | | nodePort | number | No | [Local] Kubernetes NodePort for local development. | | imagePullSecrets | object[] | No | [Local] Image pull secrets for private registries. | | imagePullSecrets[].source | "existing" | Yes | Image pull secret source. | | imagePullSecrets[].name | string | Yes | Existing Kubernetes secret name. | | imagePullPolicy | "Always" \| "IfNotPresent" \| "Never" | No | [Local] Kubernetes imagePullPolicy for the server container. Unset uses Always for :latest or untagged images and IfNotPresent otherwise. | | deploymentSpecYaml | string | No | [Local] Custom Kubernetes deployment YAML override. | | installationCommand | string | No | [Local] Command to install the MCP server package. | | userConfig | object | No | User-configurable fields shown during installation. | create_mcp_server Required RBAC permission: mcpRegistry:create Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | name | string | Yes | Display name for the MCP server. | | description | string \| null | No | Description of the MCP server. | | icon | string \| null | No | Emoji icon for the MCP server. | | docsUrl | string \| null | No | Documentation URL. | | repository | string \| null | No | Source code repository URL. | | version | string \| null | No | Version string. | | instructions | string \| null | No | Setup or usage instructions. | | labels | object[] | No | Key-value labels for organization/categorization. | | labels[].key | string | Yes | Label key. | | labels[].value | string | Yes | Label value. | | environmentId | string \| null | No | ID of the environment this server belongs to. Pass null for the default environment. Omit it to use your own environment, or the organization's landing environment for new MCP servers when you have none. | | initialGrants | object[] | No | | | initialGrants[].subject | object | Yes | | | initialGrants[].subject.type | "user" \| "team" \| "serviceAccount" \| "role" \| "organization" | Yes | | | initialGrants[].subject.id | string \| "*" | Yes | | | initialGrants[].actions | string[] | Yes | | | serverType | "local" \| "remote" \| "builtin" | No | Server type: local, remote, or builtin. | | serverUrl | string \| null | No | [Remote] The URL of the remote MCP server. | | requiresAuth | boolean | No | [Remote] Whether the server requires authentication. | | authDescription | string \| null | No | [Remote] How to set up authentication. | | authFields | object[] | No | [Remote] Authentication field definitions. | | authFields[].name | string | Yes | Auth field name. | | authFields[].label | string | Yes | Human-readable auth field label. | | authFields[].type | "header" \| "query" \| "cookie" | Yes | Where to send this auth field. | | authFields[].secret | boolean | Yes | Whether this field contains secret data. | | oauthConfig | object | No | [Remote] OAuth configuration for the server. | | command | string | No | [Local] Command to run (for example npx, uvx, or node). | | arguments | string[] | No | [Local] Command-line arguments. | | environment | object[] | No | [Local] Environment variables for the server process. | | environment[].key | string | Yes | Environment variable name. | | environment[].type | "plain_text" \| "secret" \| "boolean" \| "number" | Yes | Environment variable value type. | | environment[].value | string | No | Literal environment variable value. | | environment[].promptOnInstallation | boolean | Yes | Whether to prompt for this value during installation. | | environment[].required | boolean | No | Whether the value is required. | | environment[].description | string | No | Description shown to users. | | environment[].default | any | No | Default value. | | environment[].mounted | boolean | No | For secret values, mount as a file instead of an env var. | | envFrom | object[] | No | [Local] Import env vars from Kubernetes Secrets or ConfigMaps. | | envFrom[].type | "secret" \| "configMap" | Yes | Import source type. | | envFrom[].name | string | Yes | Secret or ConfigMap name. | | envFrom[].prefix | string | No | Optional environment variable prefix. | | dockerImage | string | No | [Local] Custom Docker image. | | serviceAccount | string | No | [Local] Kubernetes ServiceAccount name. | | transportType | "stdio" \| "streamable-http" | No | [Local] Transport type. Omit it for remote servers: streamable-http is ignored and stdio is rejected. | | httpPort | number | No | [Local] HTTP port for streamable-http transport. | | httpPath | string | No | [Local] HTTP path for streamable-http transport. | | nodePort | number | No | [Local] Kubernetes NodePort for local development. | | imagePullSecrets | object[] | No | [Local] Image pull secrets for private registries. | | imagePullSecrets[].source | "existing" | Yes | Image pull secret source. | | imagePullSecrets[].name | string | Yes | Existing Kubernetes secret name. | | imagePullPolicy | "Always" \| "IfNotPresent" \| "Never" | No | [Local] Kubernetes imagePullPolicy for the server container. Unset uses Always for :latest or untagged images and IfNotPresent otherwise. | | deploymentSpecYaml | string | No | [Local] Custom Kubernetes deployment YAML override. | | installationCommand | string | No | [Local] Command to install the MCP server package. | | userConfig | object | No | User-configurable fields shown during installation. | deploy_mcp_server Required RBAC permission: update on the MCP registry entry (granted per item) Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | catalogId | string | Yes | The catalog ID of the MCP server to deploy. | | scope | "personal" \| "team" \| "org" | No | Visibility scope for the deployment: 'personal' (default), 'team' (requires teamId), or 'org' (admins only, visible to all org members). | | teamId | string | No | Optional team ID for a team-scoped deployment (required when scope='team'). | | agentIds | string[] | No | Optional agent IDs to assign the server's tools to after deployment. | list_mcp_server_deployments Required RBAC permission: mcpRegistry:read This tool takes no arguments. get_mcp_server_logs Required RBAC permission: mcpRegistry:read Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | serverId | string | Yes | The deployment ID of the MCP server. | | lines | integer | No | Number of log lines to retrieve. | reload_mcp_server_tools Required RBAC permission: mcpServerInstallation:create Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | serverId | string | Yes | The deployment ID of the MCP server whose tools should be refreshed. Use list_mcp_server_deployments to find it. | MCP Gateways | Tool | Description | Permission | |------|-------------|--------------------------| | create_mcp_gateway | Create a new MCP gateway with the specified name, optional labels, and optional assigned knowledge bases or knowledge connectors. | mcpGateway:create | | get_mcp_gateway | Get a specific MCP gateway by ID or name. | mcpGateway:read | | edit_mcp_gateway | Edit an existing MCP gateway. | update on the MCP gateway (granted per item) | create_mcp_gateway Required RBAC permission: mcpGateway:create Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | initialGrants | object[] | No | | | initialGrants[].subject | object | Yes | | | initialGrants[].subject.type | "user" \| "team" \| "serviceAccount" \| "role" \| "organization" | Yes | | | initialGrants[].subject.id | string \| "*" | Yes | | | initialGrants[].actions | string[] | Yes | | | name | string | Yes | Name for the new resource. | | labels | object[] | No | 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. | | 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. | | 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. | get_mcp_gateway Required RBAC permission: mcpGateway:read Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | string | No | The ID of the MCP gateway to fetch. Prefer the ID when you already have it. | | name | string | No | The exact name of the MCP gateway to fetch when you do not already have the ID. | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | id | string | Yes | The resource ID. | | name | string | Yes | The resource name. | | description | string \| null | Yes | The resource description, if any. | | icon | string \| null | Yes | The emoji icon, if configured. | | scope | "personal" \| "team" \| "org" | Yes | The visibility scope. | | toolExposureMode | "full" \| "search_and_run_only" | Yes | How tools are loaded for MCP clients and models. | | accessAllTools | boolean | Yes | Whether search_tools/run_tool may dynamically access every tool the calling user can access. | | accessAllSubagents | boolean | Yes | Whether the agent may delegate to every internal agent the calling user can access. | | agentType | "agent" \| "llm_proxy" \| "mcp_gateway" \| "profile" | Yes | The resource type. | | systemPrompt | string \| null | No | | | teams | object[] | Yes | The teams attached to it. | | teams[].id | string | Yes | The team ID. | | teams[].name | string | Yes | The team name. | | labels | object[] | Yes | Assigned labels. | | labels[].key | string | Yes | The label key. | | labels[].value | string | Yes | The label value. | | tools | object[] | Yes | Assigned tools. | | tools[].id | string | Yes | The assigned tool ID. | | tools[].name | string | Yes | The tool name. | | tools[].description | string \| null | Yes | The tool description, if any. | | tools[].catalogId | string \| null | Yes | The MCP catalog ID the tool comes from, if any. | | knowledgeBaseIds | string[] | Yes | Assigned knowledge base IDs. | | connectorIds | string[] | Yes | Assigned knowledge connector IDs. | | suggestedPrompts | object[] | Yes | Configured suggested prompts. | | suggestedPrompts[].summaryTitle | string | Yes | The short title shown in the chat UI. | | suggestedPrompts[].prompt | string | Yes | The suggested prompt text. | edit_mcp_gateway Required RBAC permission: update on the MCP gateway (granted per item) Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | string | Yes | The ID of the MCP gateway to edit. Use get_mcp_gateway to look it up by name first if needed. | | description | string \| null | No | New description for the MCP gateway. | | icon | string \| null | No | New emoji icon for the MCP gateway. | | labels | object[] | No | Replace the MCP gateway's labels with this set. | | labels[].key | string | Yes | | | labels[].value | string | Yes | | | name | string | No | New name for the MCP gateway. | | toolExposureMode | "full" \| "search_and_run_only" | No | How tools should be loaded for MCP clients and models. | | knowledgeBaseIds | string[] | No | Replace the MCP gateway's assigned knowledge bases with this set. | | connectorIds | string[] | No | Replace the MCP gateway's directly assigned knowledge connectors with this set. | Tool Assignment | Tool | Description | Permission | |------|-------------|--------------------------| | bulk_assign_tools_to_agents | Assign multiple tools to multiple agents in bulk with validation and error handling | update on the agent (granted per item) | | bulk_remove_tools_from_agents | Remove multiple tools from multiple agents in bulk. | update on the agent (granted per item) | | bulk_assign_tools_to_mcp_gateways | Assign multiple tools to multiple MCP gateways in bulk with validation and error handling | update on the MCP gateway (granted per item) | bulk_assign_tools_to_agents Required RBAC permission: update on the agent (granted per item) Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | assignments | object[] | Yes | Assignments to create or update for agents. | | assignments[].toolId | string | Yes | The ID of the tool to assign. | | assignments[].resolveAtCallTime | boolean | No | When true, resolve credentials and execution target at tool call time. Prefer this for builder flows. | | assignments[].credentialResolutionMode | "static" \| "dynamic" \| "enterprise_managed" | No | | | assignments[].mcpServerId | string \| null | No | Optional MCP server installation to pin the tool to when using static credential resolution. | | assignments[].agentId | string | Yes | The agent ID to assign the tool to. | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | succeeded | object[] | Yes | Assignments that succeeded. | | succeeded[].agentId | string | Yes | The target agent ID. | | succeeded[].toolId | string | Yes | The tool ID. | | succeeded[].error | string | No | Validation or assignment error. | | succeeded[].errorCode | "not_found" \| "validation_error" \| "forbidden" | No | Structured assignment error code. | | succeeded[].errorType | string | No | Structured assignment error type. | | failed | object[] | Yes | Assignments that failed. | | failed[].agentId | string | Yes | The target agent ID. | | failed[].toolId | string | Yes | The tool ID. | | failed[].error | string | No | Validation or assignment error. | | failed[].errorCode | "not_found" \| "validation_error" \| "forbidden" | No | Structured assignment error code. | | failed[].errorType | string | No | Structured assignment error type. | | duplicates | object[] | Yes | Assignments skipped because they already existed. | | duplicates[].agentId | string | Yes | The target agent ID. | | duplicates[].toolId | string | Yes | The tool ID. | | duplicates[].error | string | No | Validation or assignment error. | | duplicates[].errorCode | "not_found" \| "validation_error" \| "forbidden" | No | Structured assignment error code. | | duplicates[].errorType | string | No | Structured assignment error type. | bulk_remove_tools_from_agents Required RBAC permission: update on the agent (granted per item) Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | removals | object[] | Yes | Tool removals to apply to agents. | | removals[].agentId | string | Yes | The agent ID to remove the tool from. | | removals[].toolId | string | Yes | The ID of the tool to remove. | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | succeeded | object[] | Yes | Removals that took effect. | | succeeded[].agentId | string | Yes | The target agent ID. | | succeeded[].toolId | string | Yes | The tool ID. | | succeeded[].error | string | No | Permission or removal error. | | notAssigned | object[] | Yes | Removals skipped because the tool was not assigned to the agent (Custom mode). | | notAssigned[].agentId | string | Yes | The target agent ID. | | notAssigned[].toolId | string | Yes | The tool ID. | | notAssigned[].error | string | No | Permission or removal error. | | failed | object[] | Yes | Removals that failed (e.g. no permission, agent not found, or a tool that cannot be excluded). | | failed[].agentId | string | Yes | The target agent ID. | | failed[].toolId | string | Yes | The tool ID. | | failed[].error | string | No | Permission or removal error. | bulk_assign_tools_to_mcp_gateways Required RBAC permission: update on the MCP gateway (granted per item) Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | assignments | object[] | Yes | Assignments to create or update for MCP gateways. | | assignments[].toolId | string | Yes | The ID of the tool to assign. | | assignments[].resolveAtCallTime | boolean | No | When true, resolve credentials and execution target at tool call time. Prefer this for builder flows. | | assignments[].credentialResolutionMode | "static" \| "dynamic" \| "enterprise_managed" | No | | | assignments[].mcpServerId | string \| null | No | Optional MCP server installation to pin the tool to when using static credential resolution. | | assignments[].mcpGatewayId | string | Yes | The MCP gateway ID to assign the tool to. | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | succeeded | object[] | Yes | Assignments that succeeded. | | succeeded[].mcpGatewayId | string | Yes | The target MCP gateway ID. | | succeeded[].toolId | string | Yes | The tool ID. | | succeeded[].error | string | No | Validation or assignment error. | | succeeded[].errorCode | "not_found" \| "validation_error" \| "forbidden" | No | Structured assignment error code. | | succeeded[].errorType | string | No | Structured assignment error type. | | failed | object[] | Yes | Assignments that failed. | | failed[].mcpGatewayId | string | Yes | The target MCP gateway ID. | | failed[].toolId | string | Yes | The tool ID. | | failed[].error | string | No | Validation or assignment error. | | failed[].errorCode | "not_found" \| "validation_error" \| "forbidden" | No | Structured assignment error code. | | failed[].errorType | string | No | Structured assignment error type. | | duplicates | object[] | Yes | Assignments skipped because they already existed. | | duplicates[].mcpGatewayId | string | Yes | The target MCP gateway ID. | | duplicates[].toolId | string | Yes | The tool ID. | | duplicates[].error | string | No | Validation or assignment error. | | duplicates[].errorCode | "not_found" \| "validation_error" \| "forbidden" | No | Structured assignment error code. | | duplicates[].errorType | string | No | Structured assignment error type. | Guardrails | Tool | Description | Permission | |------|-------------|--------------------------| | list_peer_messages | List held messages as JSON: {"messages":[{"message_id":"id","expires_at":"ISO-8601"}]}. | None | | read_peer_message | Return a held message as text, or refusal feedback with remedy offers. | None | | get_openappa_yell | Read a saved OpenAPPA report from the current organization, including its originating user or service account. | log:read | | resolve_openappa_yell | Mark an OpenAPPA yell resolved, or reopen it with resolved=false. | log:read | | list_openappa_yells | List the organization's saved OpenAPPA yells, newest first, with each one's id, session, tool call, a shortened message and whether it is resolved. | log:read | | list_openappa_consults | List the external consults OpenAPPA recorded for one session, newest first: every annotator, context provider, authority, sanitizer and audience source it asked, with the outcome, the HTTP status, ... | log:read | | create_guardrails_repository | Create a private policy repository from the OpenAPPA configuration template, seed it with the current policy and battery declarations, and start Git sync. | organizationSettings:update | | connect_guardrails_repository | Make a policy file in an existing GitHub repository or GitLab project the organization's OpenAPPA policy source, pull it now, and keep it in sync. | organizationSettings:update | | sync_guardrails_repository | Pull the policy file from the connected Git repository now instead of waiting for the next scheduled sync, so a merged policy or validation pull request takes effect. | organizationSettings:update | | yell | Send feedback about OpenAPPA, with a diagnostic archive for review in the Guardrails Yells tab. | None | | get_guardrails_policy | Read organization.appa.toml and its revision before changing guardrails. | guardrailsPolicy:read | | inspect_guardrails_server | Inspect one caller-readable MCP catalog's stored tools and current policy coverage. | guardrailsPolicy:read | | list_guardrails_battery_fits | List the batteries that fit the MCP servers you can see and are not declared yet, or only those fitting one server when mcpServerId is a catalog ID. | guardrailsPolicy:read | | validate_guardrails_policy | Validate proposed organization.appa.toml without applying changes. | guardrailsPolicy:read | | preview_guardrails_policy_change | Validate a proposed change to organization.appa.toml and return its unified diff and changed line counts. | guardrailsPolicy:read | | update_guardrails_policy | Publish a change to organization.appa.toml. | guardrailsPolicy:update | | bind_guardrails_credential | Bind one battery credential variable to a runtime credential key, or pass key null to unbind it. | guardrailsPolicy:update | | get_openappa_policy_tests | Read the authoritative .appa validation files, their version, configured directory and accepted Git commit. | guardrailsPolicy:read | | run_openappa_policy_tests | Replay saved validations against the current policy and record the result in validation run history. | guardrailsPolicy:update | | preview_guardrails_validation_change | Validate a proposed change to the .appa validation files and replay it. | guardrailsPolicy:read | | update_guardrails_validation | Save a change to the .appa validation files. | guardrailsPolicy:update | | get_guardrails_policy_change_status | Check the review state of an OpenAPPA policy pull request and whether Git sync has processed the merged policy. | guardrailsPolicy:read | | get_remedy_plans | Read why the organization's guardrails policy blocked a tool call, and which remedy plans the policy offers. | None | | execute_remedy_plan | Apply a remedy plan that the organization's guardrails policy offers for a blocked call. | None | | list_runtime_credentials | List reusable credential definitions visible to the caller, including whether a personal or organization connection is configured. | credential:read | | get_runtime_credential | Read one reusable credential definition and its usage. | credential:read | | create_runtime_credential | Create credential metadata. | credential:create | | update_runtime_credential | Update metadata for an existing credential. | update on the credential (granted per item) | | delete_runtime_credential | Delete an unused credential and its connection. | delete on the credential (granted per item) | | request_runtime_credential_setup | Ask the person to create and connect a GitHub App through the native chat dialog. | credential:create | | request_battery_credentials | Show the person one card in Archestra chat for the tokens these batteries need: what each battery adds, how to make its token, and a picker of the organization's credentials with an option to add a... | credential:create | list_peer_messages Required RBAC permission: None This tool takes no arguments. read_peer_message Required RBAC permission: None Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | message_id | string | Yes | | get_openappa_yell Required RBAC permission: log:read Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | string | Yes | | resolve_openappa_yell Required RBAC permission: log:read Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | string | Yes | | | resolved | boolean | No | false reopens a resolved yell | list_openappa_yells Required RBAC permission: log:read Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | status | "unresolved" \| "resolved" \| "all" | No | Only unresolved or resolved yells; all by default. | | sessionId | string | No | Only the yells of this session. | | search | string | No | Only yells whose message contains this text. | | cursor | string | No | The nextCursor of the previous call, with the same filters, for the next page. | list_openappa_consults Required RBAC permission: log:read Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | sessionId | string | Yes | The session to read, such as the sessionId of a yell. | | outcome | "answered" \| "unregistered" \| "unreachable" \| "dismissed" \| "non_success" \| "timeout" \| "transport" \| "malformed" \| "oversized" \| "unsupported_version" \| "module_error" \| "module_panicked" | No | Only consults with this outcome, such as non_success. | | externalName | string | No | Only consults of this external, such as github.repository-visibility. | | role | "authority" \| "sanitizer" \| "annotator" \| "audience_source" \| "input" \| "context_provider" | No | Only consults of externals in this role, such as annotator. | | cursor | string | No | The nextCursor of the previous call, with the same filters, for the next page. | create_guardrails_repository Required RBAC permission: organizationSettings:update Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | owner | string | Yes | | | name | string | Yes | | | githubAppConfigId | string | No | | | gitlabTokenId | string | No | | | interval | "15m" \| "1h" \| "1d" | No | | connect_guardrails_repository Required RBAC permission: organizationSettings:update Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | repo | string | Yes | The existing repository, as owner/name (GitLab: group/subgroup/project). | | path | string | No | Repository-relative path of the policy file. | | ref | string \| null | No | Branch, tag, or commit to follow. Omit to follow the default branch. | | githubAppConfigId | string | No | An organization GitHub App, for a GitHub repository. | | gitlabTokenId | string | No | A GitLab access token, for a GitLab project. | | interval | "15m" \| "1h" \| "1d" | No | | sync_guardrails_repository Required RBAC permission: organizationSettings:update This tool takes no arguments. yell Required RBAC permission: None Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | message | string | Yes | | | with_trajectory | boolean | Yes | | get_guardrails_policy Required RBAC permission: guardrailsPolicy:read Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | composed | boolean \| null | No | Also return effective.content, the composed policy text. Omit it unless you need the included batteries' rules. | inspect_guardrails_server Required RBAC permission: guardrailsPolicy:read Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | mcpServerId | string | Yes | The exact MCP catalog ID to inspect. | | detail | "summary" \| "full" | No | summary for a coverage overview; full adds input schemas, full descriptions and rule details. | | tools | string[] | No | Only these tools, by name or full name (__). Empty or omitted means every tool. | | offset | integer | No | The first row to return; pass the previous nextOffset. | list_guardrails_battery_fits Required RBAC permission: guardrailsPolicy:read Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | mcpServerId | string \| null | No | The catalog ID of one MCP server. Omit it for every server you can see. | validate_guardrails_policy Required RBAC permission: guardrailsPolicy:read Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | content | string | Yes | | preview_guardrails_policy_change Required RBAC permission: guardrailsPolicy:read Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | content | string \| null | No | The complete policy text. Use it only for a first policy or a full rewrite. Leave it empty when you send edits. | | edits | object[] \| null | No | Exact-text replacements applied in order to the current policy, each to the result of the one before. Use them to change an existing policy. To insert rules, replace an anchor line with the new rules followed by that same anchor line. | | edits[].oldText | string | Yes | Exact text copied from the current policy, including whitespace and line breaks. It must match one place unless replaceAll is true. | | edits[].newText | string | Yes | The text that replaces oldText. Empty deletes oldText. | | edits[].replaceAll | boolean \| null | No | Replace every match of oldText instead of exactly one. | | expectedRevision | integer | Yes | The revision get_guardrails_policy returned. | update_guardrails_policy Required RBAC permission: guardrailsPolicy:update Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | content | string \| null | No | The complete policy text. Use it only for a first policy or a full rewrite. Leave it empty when you send edits. | | edits | object[] \| null | No | Exact-text replacements applied in order to the current policy, each to the result of the one before. Use them to change an existing policy. To insert rules, replace an anchor line with the new rules followed by that same anchor line. | | edits[].oldText | string | Yes | Exact text copied from the current policy, including whitespace and line breaks. It must match one place unless replaceAll is true. | | edits[].newText | string | Yes | The text that replaces oldText. Empty deletes oldText. | | edits[].replaceAll | boolean \| null | No | Replace every match of oldText instead of exactly one. | | expectedRevision | integer | Yes | The revision get_guardrails_policy returned. | | title | string | No | | | summary | string | No | | bind_guardrails_credential Required RBAC permission: guardrailsPolicy:update Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | variable | string | Yes | The battery's credential variable, e.g. APPA_PROVIDER_GITHUB_TOKEN. | | key | string \| null | Yes | The runtime credential key to bind, or null to unbind. | get_openappa_policy_tests Required RBAC permission: guardrailsPolicy:read This tool takes no arguments. run_openappa_policy_tests Required RBAC permission: guardrailsPolicy:update Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | path | string | No | A saved validation file's path, as get_openappa_policy_tests lists it. Omit to run every saved validation. | preview_guardrails_validation_change Required RBAC permission: guardrailsPolicy:read Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | expectedRevision | integer | Yes | | | expectedVersion | string | Yes | | | changes | object | No | | | changes.upsert | object[] | No | | | changes.upsert[].path | string | Yes | | | changes.upsert[].content | string | Yes | | | changes.delete | string[] | No | | update_guardrails_validation Required RBAC permission: guardrailsPolicy:update Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | expectedRevision | integer | Yes | | | expectedVersion | string | Yes | | | changes | object | No | | | changes.upsert | object[] | No | | | changes.upsert[].path | string | Yes | | | changes.upsert[].content | string | Yes | | | changes.delete | string[] | No | | | title | string | No | | | summary | string | No | | get_guardrails_policy_change_status Required RBAC permission: guardrailsPolicy:read Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | number | integer | Yes | | get_remedy_plans Required RBAC permission: None Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | tool | string | Yes | | | arguments | string \| object | Yes | | | ruling | string | Yes | | | notice | object | Yes | | | notice.v | 1 | Yes | | | notice.call_id | string | Yes | | | notice.namespace | string | No | | | notice.custom | true | No | | execute_remedy_plan Required RBAC permission: None Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | offer_id | string | Yes | | | plan | string | No | | | label | object | No | | | label.trust | string | No | | | label.audience | string[] | No | | | return_schema | object | No | | list_runtime_credentials Required RBAC permission: credential:read This tool takes no arguments. get_runtime_credential Required RBAC permission: credential:read Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | key | string | Yes | | create_runtime_credential Required RBAC permission: credential:create Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | key | string | Yes | | | name | string | Yes | | | kind | "secret" \| "github_app" \| "github_app_user" \| "gitlab_token" | No | | | githubUrl | string \| null | No | | | appId | string \| null | No | | | installationId | string \| null | No | | | githubClientId | string \| null | No | | | githubAppCredentialKey | string \| null | No | | | gitlabUrl | string \| null | No | | | description | string | No | | | icon | string \| null | No | | | allowPersonal | boolean | No | | | allowOrganization | boolean | No | | update_runtime_credential Required RBAC permission: update on the credential (granted per item) Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | key | string | Yes | | | changes | object | Yes | | | changes.name | string | No | | | changes.githubUrl | string \| null | No | | | changes.gitlabUrl | string \| null | No | | | changes.appId | string \| null | No | | | changes.installationId | string \| null | No | | | changes.githubClientId | string \| null | No | | | changes.githubAppCredentialKey | string \| null | No | | | changes.description | string | No | | | changes.icon | string \| null | No | | delete_runtime_credential Required RBAC permission: delete on the credential (granted per item) Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | key | string | Yes | | request_runtime_credential_setup Required RBAC permission: credential:create Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | kind | "github_app" | Yes | | request_battery_credentials Required RBAC permission: credential:create Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | batteries | string[] | Yes | The battery names, e.g. slack or github. | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | batteries | object[] | Yes | | | batteries[].name | string | Yes | | | batteries[].title | string | Yes | | | batteries[].benefit | string \| null | Yes | | | batteries[].setup | string[] | Yes | | | batteries[].credentials | string[] | Yes | | Limits | Tool | Description | Permission | |------|-------------|--------------------------| | create_limit | Create a spend (token_cost), requests, or tokens limit for any supported interval. | llmLimit:create | | get_limits | Retrieve all limits, optionally filtered by entity type and/or entity ID. | llmLimit:read | | update_limit | Update mutable fields on an existing limit. | llmLimit:update | | delete_limit | Delete an existing limit by ID. | llmLimit:delete | | get_agent_token_usage | Get the total token usage (input and output) for a specific agent. | llmLimit:read | | get_llm_proxy_token_usage | Get the total token usage (input and output) for the LLM Proxy. | llmLimit:read | create_limit Required RBAC permission: llmLimit:create Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | entity_type | "organization" \| "team" \| "agent" \| "user" \| "virtual_key" \| "environment" \| "llm_oauth_client" | Yes | The type of entity to apply the limit to. | | entity_id | string | Yes | The ID of the entity (organization, team, agent, user, virtual_key, environment, or llm_oauth_client). | | limit_type | "token_cost" \| "requests" \| "tokens" \| "requests_per_minute" \| "tokens_per_minute" \| "mcp_server_calls" \| "tool_calls" | Yes | The type of limit to apply. | | limit_value | number | Yes | The limit value (tokens or count depending on limit type). | | model | string[] \| null | No | Array of model names. Omit for all models. | | cleanup_interval | "minute" \| "1h" \| "12h" \| "24h" \| "1w" \| "1m" \| "calendar_day" \| "calendar_week_sunday" \| "calendar_week_monday" \| "calendar_month" | No | Minute recovers continuously. Other intervals reset on their rolling or calendar schedule. Omit for calendar month; legacy per-minute types imply minute. | | mcp_server_name | string | No | MCP server name. Required for mcp_server_calls and tool_calls limits. | | tool_name | string | No | Tool name. Required for tool_calls limits. | | behavior | "hard" \| "soft" | No | Hard blocks exhausted requests; soft continues and records Prometheus observations. Only for token_cost, tokens and requests limits. Defaults to hard. | | reason | string \| null | No | Optional note on why the limit was set, shown with custom per-user limits. Null clears it. | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | limit | object | Yes | | | limit.throughputUsage | object | No | | | limit.throughputUsage.currentUsage | number | Yes | | | limit.throughputUsage.resetsAt | string | Yes | | | limit.id | string | Yes | The limit ID. | | limit.entityType | "organization" \| "team" \| "agent" \| "user" \| "virtual_key" \| "environment" \| "llm_oauth_client" | Yes | The limited entity type. | | limit.entityId | string | Yes | The limited entity ID. | | limit.limitType | "token_cost" \| "requests" \| "tokens" \| "requests_per_minute" \| "tokens_per_minute" \| "mcp_server_calls" \| "tool_calls" | Yes | The kind of limit. | | limit.limitValue | number | Yes | The configured limit value. | | limit.behavior | "hard" \| "soft" | Yes | | | limit.reason | string \| null | No | Why the limit was set, if a reason was given. | | limit.cleanupInterval | "minute" \| "1h" \| "12h" \| "24h" \| "1w" \| "1m" \| "calendar_day" \| "calendar_week_sunday" \| "calendar_week_monday" \| "calendar_month" | Yes | How often this limit resets. | | limit.model | string[] \| null | No | Models targeted by a cost or throughput limit. Null or empty array means all models. | | limit.mcpServerName | string \| null | No | MCP server name for MCP-specific limits, if any. | | limit.toolName | string \| null | No | Tool name for tool-specific limits, if any. | get_limits Required RBAC permission: llmLimit:read Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | entity_type | "organization" \| "team" \| "agent" \| "user" \| "virtual_key" \| "environment" \| "llm_oauth_client" | No | Optional filter by entity type. | | entity_id | string | No | Optional filter by entity ID. | | limit_type | "token_cost" \| "requests" \| "tokens" \| "requests_per_minute" \| "tokens_per_minute" \| "mcp_server_calls" \| "tool_calls" | No | Optional filter by limit type. | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | limits | object[] | Yes | | | limits[].throughputUsage | object | No | | | limits[].throughputUsage.currentUsage | number | Yes | | | limits[].throughputUsage.resetsAt | string | Yes | | | limits[].id | string | Yes | The limit ID. | | limits[].entityType | "organization" \| "team" \| "agent" \| "user" \| "virtual_key" \| "environment" \| "llm_oauth_client" | Yes | The limited entity type. | | limits[].entityId | string | Yes | The limited entity ID. | | limits[].limitType | "token_cost" \| "requests" \| "tokens" \| "requests_per_minute" \| "tokens_per_minute" \| "mcp_server_calls" \| "tool_calls" | Yes | The kind of limit. | | limits[].limitValue | number | Yes | The configured limit value. | | limits[].behavior | "hard" \| "soft" | Yes | | | limits[].reason | string \| null | No | Why the limit was set, if a reason was given. | | limits[].cleanupInterval | "minute" \| "1h" \| "12h" \| "24h" \| "1w" \| "1m" \| "calendar_day" \| "calendar_week_sunday" \| "calendar_week_monday" \| "calendar_month" | Yes | How often this limit resets. | | limits[].model | string[] \| null | No | Models targeted by a cost or throughput limit. Null or empty array means all models. | | limits[].mcpServerName | string \| null | No | MCP server name for MCP-specific limits, if any. | | limits[].toolName | string \| null | No | Tool name for tool-specific limits, if any. | update_limit Required RBAC permission: llmLimit:update Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | string | Yes | The ID of the limit to update. | | limit_value | number | No | Optional new limit value. | | limit_type | "token_cost" \| "requests" \| "tokens" \| "requests_per_minute" \| "tokens_per_minute" \| "mcp_server_calls" \| "tool_calls" | No | Same-unit legacy conversion only: requests_per_minute to requests, or tokens_per_minute to tokens. | | model | string[] \| null | No | Canonical model names; null applies to all models. | | cleanup_interval | "minute" \| "1h" \| "12h" \| "24h" \| "1w" \| "1m" \| "calendar_day" \| "calendar_week_sunday" \| "calendar_week_monday" \| "calendar_month" | No | Optional new cleanup interval for this limit. | | behavior | "hard" \| "soft" | No | Hard blocks exhausted requests; soft continues and records Prometheus observations. Only for token_cost, tokens and requests limits. Defaults to hard. | | reason | string \| null | No | Optional note on why the limit was set, shown with custom per-user limits. Null clears it. | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | limit | object | Yes | | | limit.throughputUsage | object | No | | | limit.throughputUsage.currentUsage | number | Yes | | | limit.throughputUsage.resetsAt | string | Yes | | | limit.id | string | Yes | The limit ID. | | limit.entityType | "organization" \| "team" \| "agent" \| "user" \| "virtual_key" \| "environment" \| "llm_oauth_client" | Yes | The limited entity type. | | limit.entityId | string | Yes | The limited entity ID. | | limit.limitType | "token_cost" \| "requests" \| "tokens" \| "requests_per_minute" \| "tokens_per_minute" \| "mcp_server_calls" \| "tool_calls" | Yes | The kind of limit. | | limit.limitValue | number | Yes | The configured limit value. | | limit.behavior | "hard" \| "soft" | Yes | | | limit.reason | string \| null | No | Why the limit was set, if a reason was given. | | limit.cleanupInterval | "minute" \| "1h" \| "12h" \| "24h" \| "1w" \| "1m" \| "calendar_day" \| "calendar_week_sunday" \| "calendar_week_monday" \| "calendar_month" | Yes | How often this limit resets. | | limit.model | string[] \| null | No | Models targeted by a cost or throughput limit. Null or empty array means all models. | | limit.mcpServerName | string \| null | No | MCP server name for MCP-specific limits, if any. | | limit.toolName | string \| null | No | Tool name for tool-specific limits, if any. | delete_limit Required RBAC permission: llmLimit:delete Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | string | Yes | The ID of the limit to delete. | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | success | true | Yes | | | id | string | Yes | | get_agent_token_usage Required RBAC permission: llmLimit:read Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | string | No | Optional agent ID. Defaults to the current agent. | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | id | string | Yes | | | totalInputTokens | number | Yes | | | totalOutputTokens | number | Yes | | | totalTokens | number | Yes | | get_llm_proxy_token_usage Required RBAC permission: llmLimit:read This tool takes no arguments. Output | Field | Type | Required | Description | |-------|------|----------|-------------| | id | string | Yes | | | totalInputTokens | number | Yes | | | totalOutputTokens | number | Yes | | | totalTokens | number | Yes | | Teams | Tool | Description | Permission | |------|-------------|--------------------------| | create_team | Create a new team in the organization, optionally nested under a parent team and with key-value labels. | team:create | | get_team | Retrieve a single team by its ID or name, including its current member count. | team:read † | | list_teams | List all teams in the organization, optionally filtered by a name substring. | team:read † | | edit_team | Update a team's name, description, parent, and/or labels. | team:update | | delete_team | Delete a team by ID. | team:delete | | list_team_members | List all members of a team along with their roles. | team:read † | | add_team_member | Add an organization user to a team by user ID or email, optionally as an admin. | team:read † | | update_team_member_role | Change a team member's role between admin and member. | team:read † | | remove_team_member | Remove a member from a team. | team:read † | | list_team_external_groups | List the identity provider groups linked to a team for Team Sync, with the team role each grants. | team:read | | add_team_external_group | Link an identity provider group to a team for Team Sync: on each sign-in, people in the group join the team with the link's team role, and leave it once they leave the group. | team:read | | remove_team_external_group | Unlink an identity provider group from a team's Team Sync, by link ID or by group identifier. | team:read | † This tool enforces an additional access requirement beyond its RBAC permission — see its details below. create_team Required RBAC permission: team:create Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | name | string | Yes | The name of the team. | | description | string | No | Optional human-readable description of the team. | | roles | string[] | No | Organization role identifiers to assign to the team. Members of this team and its descendants inherit their permissions. | | parent_id | string \| null | No | Optional parent team ID. Omit or pass null for a root team. | | labels | object[] | No | Optional key-value labels to assign to the team for organization and categorization (e.g. cost-center, environment). | | labels[].key | string | Yes | | | labels[].value | string | Yes | | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | team | object | Yes | | | team.id | string | Yes | The team ID. | | team.name | string | Yes | The team name. | | team.description | string \| null | Yes | The team description, if any. | | team.roles | string[] | Yes | Organization role identifiers assigned to the team and inherited by members of this team and its descendants. | | team.parentId | string \| null | Yes | The parent team ID, or null when this is a root team. | | team.organizationId | string | Yes | The organization the team belongs to. | | team.createdBy | string \| null | Yes | The ID of the user who created the team. | | team.memberCount | number | Yes | The number of members currently in the team. | | team.labels | object[] | Yes | Key-value labels assigned to the team. | | team.labels[].key | string | Yes | The label key. | | team.labels[].value | string | Yes | The label value. | | team.createdAt | string | Yes | ISO timestamp when the team was created. | | team.updatedAt | string | Yes | ISO timestamp when the team was last updated. | get_team Required RBAC permission: team:read Additional access requirement: Callers without organization-level team management (team:create) can only read teams they are a member of. Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | string | No | The ID of the team to fetch. | | name | string | No | The name of the team to fetch (within the organization). | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | team | object | Yes | | | team.id | string | Yes | The team ID. | | team.name | string | Yes | The team name. | | team.description | string \| null | Yes | The team description, if any. | | team.roles | string[] | Yes | Organization role identifiers assigned to the team and inherited by members of this team and its descendants. | | team.parentId | string \| null | Yes | The parent team ID, or null when this is a root team. | | team.organizationId | string | Yes | The organization the team belongs to. | | team.createdBy | string \| null | Yes | The ID of the user who created the team. | | team.memberCount | number | Yes | The number of members currently in the team. | | team.labels | object[] | Yes | Key-value labels assigned to the team. | | team.labels[].key | string | Yes | The label key. | | team.labels[].value | string | Yes | The label value. | | team.createdAt | string | Yes | ISO timestamp when the team was created. | | team.updatedAt | string | Yes | ISO timestamp when the team was last updated. | list_teams Required RBAC permission: team:read Additional access requirement: Callers without organization-level team management (team:create) only see teams they are a member of. Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | name | string | No | Optional case-insensitive name substring to filter by. | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | teams | object[] | Yes | | | teams[].id | string | Yes | The team ID. | | teams[].name | string | Yes | The team name. | | teams[].description | string \| null | Yes | The team description, if any. | | teams[].roles | string[] | Yes | Organization role identifiers assigned to the team and inherited by members of this team and its descendants. | | teams[].parentId | string \| null | Yes | The parent team ID, or null when this is a root team. | | teams[].organizationId | string | Yes | The organization the team belongs to. | | teams[].createdBy | string \| null | Yes | The ID of the user who created the team. | | teams[].memberCount | number | Yes | The number of members currently in the team. | | teams[].labels | object[] | Yes | Key-value labels assigned to the team. | | teams[].labels[].key | string | Yes | The label key. | | teams[].labels[].value | string | Yes | The label value. | | teams[].createdAt | string | Yes | ISO timestamp when the team was created. | | teams[].updatedAt | string | Yes | ISO timestamp when the team was last updated. | edit_team Required RBAC permission: team:update Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | string | Yes | The ID of the team to update. | | name | string | No | Optional new team name. | | description | string \| null | No | Optional new team description. Pass null to clear an existing description. | | roles | string[] | No | Replace the team’s organization role identifiers. Members of this team and its descendants inherit their permissions. Pass [] to clear; omit to leave unchanged. | | parent_id | string \| null | No | Move the team under this parent. Pass null to move it to the root; omit to leave the hierarchy unchanged. | | labels | object[] | No | Replace the team's labels with this set. Pass an empty array to remove all labels. Omit to leave labels unchanged. | | labels[].key | string | Yes | | | labels[].value | string | Yes | | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | team | object | Yes | | | team.id | string | Yes | The team ID. | | team.name | string | Yes | The team name. | | team.description | string \| null | Yes | The team description, if any. | | team.roles | string[] | Yes | Organization role identifiers assigned to the team and inherited by members of this team and its descendants. | | team.parentId | string \| null | Yes | The parent team ID, or null when this is a root team. | | team.organizationId | string | Yes | The organization the team belongs to. | | team.createdBy | string \| null | Yes | The ID of the user who created the team. | | team.memberCount | number | Yes | The number of members currently in the team. | | team.labels | object[] | Yes | Key-value labels assigned to the team. | | team.labels[].key | string | Yes | The label key. | | team.labels[].value | string | Yes | The label value. | | team.createdAt | string | Yes | ISO timestamp when the team was created. | | team.updatedAt | string | Yes | ISO timestamp when the team was last updated. | delete_team Required RBAC permission: team:delete Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | string | Yes | The ID of the team to delete. | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | success | true | Yes | | | id | string | Yes | | list_team_members Required RBAC permission: team:read Additional access requirement: Callers without organization-level team management (team:create) can only read members of teams they are a member of. Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | team_id | string | Yes | The ID of the team whose members to list. | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | members | object[] | Yes | | | members[].id | string | Yes | The team membership row ID. | | members[].teamId | string | Yes | The team the membership belongs to. | | members[].userId | string | Yes | The ID of the member user. | | members[].role | "admin" \| "member" | Yes | The member's role within the team (admin or member). | | members[].syncedFromSso | boolean | Yes | Whether this membership is managed by SSO group sync. | | members[].name | string \| null | No | The member's display name, when available. | | members[].email | string | No | The member's email, when available. | | members[].createdAt | string | Yes | ISO timestamp when the membership was created. | add_team_member Required RBAC permission: team:read Additional access requirement: Beyond team:read, the caller must be an organization-level team manager (a role granting team:create) or an admin of the target team. Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | team_id | string | Yes | The ID of the team to add the member to. | | user | string | Yes | The user to add, identified by their user ID or email address. The user must already belong to the organization. | | role | "admin" \| "member" | No | The role to assign within the team. Defaults to 'member'. | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | member | object | Yes | | | member.id | string | Yes | The team membership row ID. | | member.teamId | string | Yes | The team the membership belongs to. | | member.userId | string | Yes | The ID of the member user. | | member.role | "admin" \| "member" | Yes | The member's role within the team (admin or member). | | member.syncedFromSso | boolean | Yes | Whether this membership is managed by SSO group sync. | | member.name | string \| null | No | The member's display name, when available. | | member.email | string | No | The member's email, when available. | | member.createdAt | string | Yes | ISO timestamp when the membership was created. | update_team_member_role Required RBAC permission: team:read Additional access requirement: Beyond team:read, the caller must be an organization-level team manager (a role granting team:create) or an admin of the target team. Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | team_id | string | Yes | The ID of the team. | | user_id | string | Yes | The ID of the member user to update. | | role | "admin" \| "member" | Yes | The new role for the member (admin or member). | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | member | object | Yes | | | member.id | string | Yes | The team membership row ID. | | member.teamId | string | Yes | The team the membership belongs to. | | member.userId | string | Yes | The ID of the member user. | | member.role | "admin" \| "member" | Yes | The member's role within the team (admin or member). | | member.syncedFromSso | boolean | Yes | Whether this membership is managed by SSO group sync. | | member.name | string \| null | No | The member's display name, when available. | | member.email | string | No | The member's email, when available. | | member.createdAt | string | Yes | ISO timestamp when the membership was created. | remove_team_member Required RBAC permission: team:read Additional access requirement: Beyond team:read, the caller must be an organization-level team manager (a role granting team:create) or an admin of the target team. Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | team_id | string | Yes | The ID of the team. | | user_id | string | Yes | The ID of the member user to remove from the team. | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | success | true | Yes | | | teamId | string | Yes | | | userId | string | Yes | | list_team_external_groups Required RBAC permission: team:read Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | team_id | string | Yes | The ID of the team whose Team Sync group links to list. | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | externalGroups | object[] | Yes | | | externalGroups[].id | string | Yes | The Team Sync group link ID. | | externalGroups[].teamId | string | Yes | The team the mapping belongs to. | | externalGroups[].groupIdentifier | string | Yes | The external identity provider group identifier. | | externalGroups[].identityProviderId | string \| null | Yes | The identity provider the group is matched for, or null to match it from any provider. | | externalGroups[].role | "admin" \| "member" | Yes | The team role members of this group receive. | | externalGroups[].createdAt | string | Yes | ISO timestamp when the mapping was created. | add_team_external_group Required RBAC permission: team:read Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | team_id | string | Yes | The ID of the team to link the group to. | | group_identifier | string | Yes | The external identity provider group identifier. Format varies by provider: LDAP Distinguished Name (e.g. cn=admins,ou=groups,dc=example,dc=com), OAuth/OIDC group name from the groups claim, SAML group attribute value, or Azure AD group object ID (GUID). Matched case-insensitively. | | identity_provider_id | string | No | The ID of the identity provider to match the group for. Omit to match the group from any provider. | | role | "admin" \| "member" | No | The team role members of this group receive: member (default) or admin. | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | externalGroup | object | Yes | | | externalGroup.id | string | Yes | The Team Sync group link ID. | | externalGroup.teamId | string | Yes | The team the mapping belongs to. | | externalGroup.groupIdentifier | string | Yes | The external identity provider group identifier. | | externalGroup.identityProviderId | string \| null | Yes | The identity provider the group is matched for, or null to match it from any provider. | | externalGroup.role | "admin" \| "member" | Yes | The team role members of this group receive. | | externalGroup.createdAt | string | Yes | ISO timestamp when the mapping was created. | remove_team_external_group Required RBAC permission: team:read Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | team_id | string | Yes | The ID of the team. | | group_id | string | No | The ID of the Team Sync group link to remove. | | group_identifier | string | No | The external group identifier to remove, as an alternative to group_id. Matched case-insensitively. | Output | Field | Type | Required | Description | |-------|------|----------|-------------| | success | true | Yes | | | teamId | string | Yes | | Plugins | Tool | Description | Permission | |------|-------------|--------------------------| | list_plugins | List the plugins available to you in this organization — one line per plugin with its id, client, platforms, visibility, and file count. | plugin:read | | get_plugin | Read one plugin, including every file's exact bytes and the plugin's current contentHash. | plugin:read | | create_plugin | Create a plugin from an explicit file set. | plugin:create | | update_plugin | Update a plugin's metadata, visibility, or entire file set. | plugin:update | | edit_plugin | Make a targeted edit to one file of a plugin without resending the whole file set. | plugin:update | | delete_plugin | Delete a plugin. | plugin:delete | list_plugins Required RBAC permission: plugin:read Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | 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 plugins". | | 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. | get_plugin Required RBAC permission: plugin:read Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | string | Yes | The plugin id, as listed by list_plugins. | create_plugin Required RBAC permission: plugin:create Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | initialGrants | object[] | No | | | initialGrants[].subject | object | Yes | | | initialGrants[].subject.type | "user" \| "team" \| "serviceAccount" \| "role" \| "organization" | Yes | | | initialGrants[].subject.id | string \| "*" | Yes | | | initialGrants[].actions | string[] | Yes | | | displayName | string | Yes | Human-readable plugin name. | | description | string | No | What the plugin does. | | clientType | "claude-code" \| "claude-desktop" \| "copilot-cli" \| "codex" \| "cursor" | Yes | The client the payload targets: claude-code, claude-desktop, codex, copilot-cli, or cursor. | | supportedPlatforms | string[] | No | Operating systems the payload supports. | | files | object[] | Yes | The plugin's files as { path, content, encoding?, mode? }. Hook configuration bytes are stored verbatim — review them as code, they execute on developer machines. | | files[].path | string | Yes | | | files[].content | string | Yes | | | files[].encoding | "utf8" \| "base64" | No | | | files[].mode | "100644" \| "100755" | No | | update_plugin Required RBAC permission: plugin:update Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | string | Yes | The plugin id, as listed by list_plugins. | | displayName | string | No | Human-readable plugin name. | | description | string | No | What the plugin does. | | enabled | boolean | No | Disabled plugins are left out of future setup commands; already-installed copies are unaffected. | | supportedPlatforms | string[] | No | Operating systems the payload supports. | | baseContentHash | string | No | Required when files is provided. Use the current contentHash from get_plugin; the replacement is rejected if newer bytes landed first. | | files | object[] | No | WHEN PROVIDED, REPLACES THE PLUGIN'S ENTIRE file set. Omit it to edit only metadata/visibility. Manual plugins only — GitHub-sourced files are read-only. For a small change to one file, prefer edit_plugin over resending every file. | | files[].path | string | Yes | | | files[].content | string | Yes | | | files[].encoding | "utf8" \| "base64" | No | | | files[].mode | "100644" \| "100755" | No | | edit_plugin Required RBAC permission: plugin:update Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | string | Yes | The plugin id, as listed by list_plugins. | | baseContentHash | string | Yes | The plugin's current contentHash, as returned by get_plugin. The edit is rejected when the plugin's bytes have moved past it. | | path | string | Yes | The plugin file to edit, from the file list returned by get_plugin. Only text (utf8) files are editable — binary files are not. | | edits | object[] | No | str_replace edits applied in order to the target file; the whole edit is atomic (any failure leaves the plugin unchanged). Pass either edits or replacementContent, never both. | | edits[].old_str | string | Yes | Exact text to replace; must occur exactly once in the target (add surrounding context to disambiguate). | | edits[].new_str | string | Yes | Replacement text (may be empty to delete). | | replacementContent | string | No | The complete new content of the target file, replacing it outright with no old_str matching. Pass either edits or replacementContent, never both. | delete_plugin Required RBAC permission: plugin:delete Input | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | string | Yes | The plugin id, as listed by list_plugins. |