> ## Documentation Index
> Fetch the complete documentation index at: https://developers.arg.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents overview

> How an arg.ai agent run works: the chat it lives in, the workspace it acts on, and the tools it reaches for.

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.

<CardGroup cols={3}>
  <Card title="A chat" icon="comments">
    Holds the conversation. Send a second message to the same chat and the agent
    keeps everything it already learned.
  </Card>

  <Card title="A workspace" icon="hard-drive">
    The files it reads and writes, and the sandbox it runs commands in. Without
    one the agent can only talk.
  </Card>

  <Card title="A model" icon="microchip">
    Picked per run with `model`. Defaults to your organization's setting.
  </Card>
</CardGroup>

## The shape of the API

```bash theme={null}
# 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](/guides/agents/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](/guides/actions)**      | Typed capabilities: image and video generation, integration calls, data lookups | The Action catalog, reached through `search_actions` and `run_action`. |
| **[Skills](/guides/agents/skills)** | Instructions you write for recurring work                                       | `.skills/` files in the workspace.                                     |
| **[Connectors](/guides/mcp)**       | 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](/api-reference/agent/send-message)                 |
| Working inside Claude Code, Codex, or another MCP client   | The [MCP server](/guides/mcp)                                      |
| Calling one capability directly, with no agent in the loop | The [tool endpoints](/guides/tools) and [Actions](/guides/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](/guides/agents/unattended).

## Next

<CardGroup cols={2}>
  <Card title="Agent runs" icon="play" href="/guides/agents/runs">
    Start, watch, steer, and stop a run.
  </Card>

  <Card title="Skills and subagents" icon="book" href="/guides/agents/skills">
    Teach a workspace how you want recurring work done.
  </Card>

  <Card title="Unattended runs" icon="robot" href="/guides/agents/unattended">
    Service accounts, automations, and telling a human when it is done.
  </Card>

  <Card title="Quickstart" icon="bolt" href="/guides/quickstart">
    The whole loop in curl, from an empty workspace to a downloaded artifact.
  </Card>
</CardGroup>