Documentation | Agent Configs

Agent Configs

AgentConfigsResource

Methods

client.agent_configs.create() ->

post/v5/agent_configs

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.

Parameters

harness: Literal["claude-code", "codex", "litellm"]

Harness strategy. See Harness enum for supported values.

"claude-code"

"codex"

"litellm"

model: str

(maxLength: 255, minLength: 1)

name: str

(maxLength: 255, minLength: 1)

system_prompt: str

(maxLength: 100000, minLength: 1)

allowed_tools: Optional[List[Literal["Read", "Write", "Edit", "Bash", "Glob", "Grep", "List", "WebFetch", "WebSearch", "Task", "TodoWrite", "NotebookEdit", "ExitPlanMode", "Slack", "Linear", "GitHub", "Confluence", "Notion", "Datadog", "PagerDuty", "Salesforce", "Figma", "Granola"]]]

Tools enabled for this config. See AllowedTool enum for the catalogue.

"Read"

"Write"

"Edit"

"Bash"

"Glob"

"Grep"

"List"

"WebFetch"

"WebSearch"

"Task"

"TodoWrite"

"NotebookEdit"

"ExitPlanMode"

"Slack"

"Linear"

"GitHub"

"Confluence"

"Notion"

"Datadog"

"PagerDuty"

"Salesforce"

"Figma"

"Granola"

description: Optional[str]

(maxLength: 2000)

persistent_workspace: Optional[

bool

]

Give tasks a persistent /workspace that survives sandbox death. Fixed for a task's life; defaults off.

repos: Optional[Iterable[

Repo

]]

Per-config repo override. None uses the deployment default; an empty list clones nothing.

url: str

(maxLength: 2048, minLength: 1)

depth: Optional[int]

(minimum: 1)

path: Optional[str]

(maxLength: 1024)

Returns

class AgentConfigCreateResponse:

id: str

allowed_tools: List[str]

created_at:

datetime

(format: date-time)

harness: str

model: str

name: str

system_prompt: str

updated_at:

datetime

(format: date-time)

description: Optional[str]

object: Optional[Literal["agent_config"]]

(default: "agent_config")

persistent_workspace: Optional[bool]

repos: Optional[List[

Repo

]]

Request example

import os
from scale_gp_beta import SGPClient

client = SGPClient(
    api_key=os.environ.get("SGP_API_KEY"),  # This is the default and can be omitted
)
agent_config = client.agent_configs.create(
    harness="claude-code",
    model="x",
    name="x",
    system_prompt="x",
)
print(agent_config.id)

200Example

{
  "id": "id",
  "allowed_tools": [
    "string"
  ],
  "created_at": "2019-12-27T18:11:19.117Z",
  "harness": "harness",
  "model": "model",
  "name": "name",
  "system_prompt": "system_prompt",
  "updated_at": "2019-12-27T18:11:19.117Z",
  "description": "description",
  "object": "agent_config",
  "persistent_workspace": true,
  "repos": [
    {
      "url": "x",
      "depth": 1,
      "path": "path"
    }
  ]
}

client.agent_configs.list() -> SyncCursorPage[

AgentConfigListResponse

]

get/v5/agent_configs

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.

client.agent_configs.list_mcp_tools() ->

AgentConfigListMcpToolsResponse

get/v5/agent_configs/mcp_tools

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.

client.agent_configs.retrieve() ->

AgentConfigRetrieveResponse

get/v5/agent_configs/{agent_config_id}

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.

client.agent_configs.update(, ) ->

AgentConfigUpdateResponse

patch/v5/agent_configs/{agent_config_id}

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.

client.agent_configs.delete() ->

AgentConfigDeleteResponse

delete/v5/agent_configs/{agent_config_id}

Permanently delete an agent config; this is a hard delete, not an archive, so the row is removed and cannot be restored.

Because a config is only a template, deleting it does not stop or alter any task already created from it. A user caller can only delete a config they created unless fine-grained access control grants access. The response echoes the deleted id.

Domain types

class AgentConfigCreateResponse: ...

class AgentConfigDeleteResponse: ...

List[Literal["Slack", "Linear", "GitHub", "Confluence", "Notion", "Datadog", "PagerDuty", "Salesforce", "Figma", "Granola"]]

class AgentConfigListResponse: ...

class AgentConfigRetrieveResponse: ...

class AgentConfigUpdateResponse: ...