Agents overview

An agent run is one turn of work: you send a message, the agent plans, calls tools, writes files, and finishes with a response. Runs are asynchronous - the API starts one and hands you an id to poll, so a run can take minutes without holding a connection open. Three things define a run.

A chat

Holds the conversation. Send a second message to the same chat and the agent keeps everything it already learned.

A workspace

The files it reads and writes, and the sandbox it runs commands in. Without one the agent can only talk.

A model

Picked per run with model. Defaults to your organization’s setting.

The shape of the API

# 1. Start a run. Returns job_id and call_id.
POST /api/agent/message   { "message": "...", "workspace_id": "..." }

# 2. Poll until it finishes.
GET  /api/agent/status/{call_id}?chat_id=...

# 3. Collect what it produced.
GET  /api/workspaces/{workspace_id}/files/tree

That is the whole loop. Agent runs covers it end to end, including queueing, steering, and stopping a turn.

What an agent can do

An agent’s abilities come from four layers, and each is something you control.

Layer	What it is	Where it comes from
Tools	Shell, file read/write/edit, search, web fetch, code execution	Built in. Available on any run with a `workspace_id`.
Actions	Typed capabilities: image and video generation, integration calls, data lookups	The Action catalog, reached through `search_actions` and `run_action`.
Skills	Instructions you write for recurring work	`.skills/` files in the workspace.
Connectors	Your own MCP servers and third-party integrations	Connected once per organization, then activated per workspace.

The same tool surface is available three ways, so pick whichever fits where you already are:

You are	Use
Writing a service or a script that drives the agent	The Agent API
Working inside Claude Code, Codex, or another MCP client	The MCP server
Calling one capability directly, with no agent in the loop	The tool endpoints and Actions

Choosing how much rope to give it

Every run takes optional limits, and they matter more for unattended work than for interactive chat.

Option	Effect
`read_only`	The agent can read the workspace but not modify it.
`max_tool_iterations`	Caps tool-use rounds for the turn, from 1 to 100.
`disabled_skills`, `disabled_agents`	Withholds specific skills or subagents from the turn.
`reasoning_effort`	`none`, `low`, `medium`, or `high`, clamped to what the model supports.

Who the agent acts as

A run inherits the access of the credential that started it. A user-owned API key acts as you; a service-account key acts as the service account and sees only what that account was granted. For unattended work, give a service account its own workspace access rather than reusing a personal key - see Unattended runs.

Agent runs

Start, watch, steer, and stop a run.

Skills and subagents

Teach a workspace how you want recurring work done.

Unattended runs

Service accounts, automations, and telling a human when it is done.

Quickstart

The whole loop in curl, from an empty workspace to a downloaded artifact.

Getting started

Building with agents

Core concepts

Apps

Arg SDK

Integrations

Command line

Recipes & patterns

Changelog

Agents overview

A chat

A workspace

A model

The shape of the API

What an agent can do

Choosing how much rope to give it

Who the agent acts as

Next

Agent runs

Skills and subagents

Unattended runs

Quickstart

A chat

A workspace

A model

​The shape of the API

​What an agent can do

​Choosing how much rope to give it

​Who the agent acts as

​Next

Agent runs

Skills and subagents

Unattended runs

Quickstart

The shape of the API

What an agent can do

Choosing how much rope to give it

Who the agent acts as

Next