Create a reusable agent configuration (system prompt, harness, model, allowed tools) under the caller's account.

The config is a template that a chat session or a non-chat trigger later turns into task params; creating one does not start any task. persistent_workspace opts tasks made from this config into a durable /workspace that survives sandbox death (off by default, and fixed once a task starts), and repos overrides which repositories provisioning clones into that workspace — omit it (null) to use the deployment default, or pass an empty list to clone nothing. A repos override is rejected with a 422 on the model-agnostic (litellm) harness unless persistent_workspace is also true, because non-persistent litellm tasks run in a pre-cloned warm-pool sandbox where the override would be ignored. allowed_tools may name MCP servers (Slack, Linear, GitHub, ...) alongside harness tools, and granting an MCP server name authorizes every tool it exposes.

List agent configurations visible to the caller, with cursor-based pagination.

A user caller sees only the configs they created unless fine-grained access control (FGAC) grants them access to others; a service-account caller sees every config under the account. This returns the stored config records as-is — use {agent_config_id}/resolve instead when you need a config projected into the params a task would run with. Because deleting a config removes it outright rather than archiving it, there are no archived configs to page through here.

Return the fixed set of tool names that route to MCP servers rather than harness-provided tools.

These are the subset of allowed_tools values (Slack, Linear, GitHub, ...) the platform treats as MCP servers; the list is a static enum, not account data, so it is identical for every caller. It is exposed mainly so the generated SDK carries the McpTool type and the frontend can assert its own MCP-versus-harness tool classifier against the backend to prevent drift. It does not list configs or the tools actually granted to any particular config.

Fetch a single stored agent configuration by id, including its persistent_workspace flag and any repos override.

This returns the saved record as-is and does not compute task params; use {agent_config_id}/resolve when you need the config projected into the params a task would run with. A user caller can only read a config they created unless fine-grained access control grants access, while a service account can read any config under the account; a missing or out-of-scope id returns a 404.

Partially update a stored agent config; only fields present in the request body are changed.

persistent_workspace and repos are both patchable — an explicit null on repos clears the override back to the deployment default, while the always-present fields (name, system_prompt, harness, allowed_tools, model, and persistent_workspace) reject an explicit null. Because persistent_workspace and repos are read when a task is created and are fixed for a task's life, changing them affects only tasks created afterward, not one already running. The optional task_id query parameter opts into a live-config side effect: after the row is persisted, the changed pass-through fields (system_prompt, model, harness, and allowed_tools split into harness tools versus MCP servers) are shallow-merged into that running task's params on Agentex in a background task so the worker picks them up on its next turn; persistent_workspace and repos are intentionally not forwarded to a running task. That side effect runs after the response is sent, is best-effort, and no-ops if the task does not exist or the caller does not own it. A user caller can only update a config they created unless fine-grained access control grants access.