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

# Agents

> Run coding agents on a schedule or triggered by events.

![Agents](https://mintcdn.com/test-8862363a/_KF7n4fDwDrxMgZe/images/automation-light.png?fit=max\&auto=format\&n=_KF7n4fDwDrxMgZe\&q=85\&s=13a9adad2d53842e6be32b3bfbea77ac)

Run coding agents in the background, on a schedule or triggered by events. A Sentry error gets fixed within seconds. Docs stay in sync with your code. Security vulnerabilities get caught before they become problems.

Each agent runs in a secure [sandbox](https://docs.tembo.io/features/sandbox/overview.md) with full codebase and repository access and your configured [MCP servers](https://docs.tembo.io/integrations/mcp.md).

## Agent harness

Tembo is harness and model agnostic. For each agent you configure, you pick the harness (and model) that runs in the session it spawns, for example Claude Code with Sonnet 5.5, Codex with GPT-5.4, or Cursor. Set a default per agent, or override per session.

See [Models](https://docs.tembo.io/features/models.md) for the full supported model list, BYOK details, and AWS Bedrock BYOK support.

> [accordion] Claude Code
>
> Anthropic's Claude models. Best balance of quality, reliability, and cost.
>
> **Models:** Opus 5.5, Opus 5, Fable 5.2, Fable 5.1, Fable 5, Sonnet 5.5, Haiku 5.5, Opus 4.8, Opus 4.7, Opus 4.6, Opus 4.5

> [accordion] Codex
>
> OpenAI's GPT models with configurable reasoning effort (low, medium, high, xhigh). GPT-6.1 Sol, GPT-6.1 Terra, GPT-6 Astra, GPT-6 Sol, GPT-5.6 Sol, and GPT-5.6 Terra also support max and ultra; GPT-6.2 Astra, GPT-6.2 Sol, GPT-6 Luna, and GPT-5.6 Luna also support max.
>
> **Models:** GPT-6.2 Astra, GPT-6.2 Sol, GPT-6.1 Sol, GPT-6.1 Terra, GPT-6 Astra, GPT-6 Sol, GPT-6 Luna, GPT-5.6 Sol, GPT-5.6 Terra, GPT-5.6 Luna, GPT-5.5 Pro, GPT-5.4, GPT-5.3 Codex, GPT-5.4 Mini, GPT-5.4 Nano

> [accordion] Cursor
>
> Multi-provider via Cursor CLI.
>
> **Models:** Composer 2.5, Composer 2, Composer 2 Fast, Composer 1.5, Opus 5.5, Opus 5, Sonnet 5.5, Haiku 5.5, Opus 4.8, Opus 4.7, Opus 4.6, Opus 4.5, GPT-5.6 Sol, GPT-5.6 Terra, GPT-5.3 Codex, GPT-5.3 Codex Spark, Gemini 3.1 Pro, Gemini 3.5 Flash, Grok 4.7

> [accordion] Opencode
>
> Multi-provider support: Anthropic, OpenAI, and OSS models.
>
> **Models:** Opus 5.5, Opus 5, Fable 5.2, Fable 5.1, Fable 5, Sonnet 5.5, Haiku 5.5, Opus 4.8, Opus 4.7, Opus 4.6, Opus 4.5, GPT-6.2 Astra, GPT-6.2 Sol, GPT-6.1 Sol, GPT-6.1 Terra, GPT-6 Astra, GPT-6 Sol, GPT-6 Luna, GPT-5.6 Sol, GPT-5.6 Terra, GPT-5.6 Luna, GPT-5.5 Pro, GPT-5.4, GPT-5.3 Codex, GPT-5.4 Mini, GPT-5.4 Nano, Gemini 3.1 Pro, Gemini 3.5 Flash, Grok 4.7, GLM 5.3, GLM 5.3 Flash, Kimi K3, DeepSeek V4 Pro, DeepSeek V4.1 Flash, MiniMax M2.7, MiniMax M3

> [accordion] Amp
>
> Claude-powered with automatic model selection.

> [accordion] Pi
>
> A minimal, extensible terminal coding harness with multi-provider support.
>
> **Models:** Opus 5.5, Opus 5, Fable 5.2, Fable 5.1, Fable 5, Sonnet 5.5, Haiku 5.5, Opus 4.8, Opus 4.7, Opus 4.6, Opus 4.5, GPT-6.2 Astra, GPT-6.2 Sol, GPT-6.1 Sol, GPT-6.1 Terra, GPT-6 Astra, GPT-6 Sol, GPT-6 Luna, GPT-5.6 Sol, GPT-5.6 Terra, GPT-5.6 Luna, GPT-5.5 Pro, GPT-5.4, GPT-5.3 Codex, GPT-5.4 Mini, GPT-5.4 Nano, GPT-5.2, Grok 4.7, GLM 5.3, GLM 5.3 Flash, Kimi K3, DeepSeek V4 Pro, DeepSeek V4.1 Flash, MiniMax M2.7, MiniMax M3

> [accordion] fx
>
> A tiny, open, native coding agent with multi-provider model support.
>
> **Models:** Opus 5.5, Opus 5, Fable 5.2, Fable 5.1, Fable 5, Sonnet 5.5, Haiku 5.5, Opus 4.8, Opus 4.7, Opus 4.6, Opus 4.5, GPT-6.2 Astra, GPT-6.2 Sol, GPT-6.1 Sol, GPT-6.1 Terra, GPT-6 Astra, GPT-6 Sol, GPT-6 Luna, GPT-5.6 Sol, GPT-5.6 Terra, GPT-5.6 Luna, GPT-5.5 Pro, GPT-5.4, GPT-5.3 Codex, GPT-5.4 Mini, GPT-5.4 Nano, Gemini 3.1 Pro, Gemini 3.5 Flash, GLM 5.3, GLM 5.3 Flash, Kimi K3, DeepSeek V4 Pro, DeepSeek V4.1 Flash, MiniMax M2.7, MiniMax M3

## Triggers

These are just examples to give you a rough idea. You decide how to set this up, there are no limitations.

### Scheduled

Run agents at regular intervals.

| Schedule | Example |
| - | - |
| **Hourly** | Monitor for CI failures, new Sentry errors |
| **Daily** | Generate changelogs, post standup summaries |
| **Weekly** | Clean up stale TODOs, security scans |
| **Monthly** | Dependency audits, documentation reviews |

### Event-driven

React to events from your integrations in real-time.

| Integration | Events |
| - | - |
| **GitHub** | PR opened, PR merged, issue created, comment added |
| **GitLab** | Merge request opened, merged, issue created |
| **Sentry** | New error, error spike, regression detected |
| **Linear** | Issue created, issue updated, status changed |
| **Slack** | Message in channel, @tembo mention |

### Webhooks

Trigger an agent on demand from CI, internal tools, or any service that can send an HTTP request. Send a `POST` request with an [API key](https://docs.tembo.io/api.md#authentication) to the agent's runs endpoint.

| Deployment | URL |
| - | - |
| Tembo API | `https://api.tembo.io/v1/agents/{agentId}/runs` |
| Self-hosted | `https://{deployment-origin}/api/public-api/v1/agents/{agentId}/runs` |

The agent ID is the UUID at the end of the agent's URL in the dashboard (`https://app.tembo.io/<workspace>/agents/<AGENT_ID>`). Agent keys (macros) aren't accepted and return `400`.

```bash Tembo API theme={null}
curl -X POST "https://api.tembo.io/v1/agents/AGENT_ID/runs" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"issue_url": "https://github.com/org/repo/issues/42"}'
```

```bash Self-hosted theme={null}
curl -X POST "https://tembo.example.com/api/public-api/v1/agents/AGENT_ID/runs" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"issue_url": "https://github.com/org/repo/issues/42"}'
```

Tembo responds with `201` once the run is queued. The response confirms the run is queued, not that it finished:

```json theme={null}
{
  "jobId": "96ea1b5b-fc94-4c4a-9b16-0dba674e4533",
  "runId": "5f0c8d1e-7a42-4c1b-9e3d-2b6a8f4c9d10",
  "agentId": "10dc26a2-9e2e-4a25-9f1b-4791fa2edf9c",
  "status": "queued"
}
```

Use `runId` to [follow the run to its session](#follow-a-run-to-its-session).

#### Payload

The request body is optional. When you send one, it must be a JSON object. Send your fields at the top level; you don't need to wrap them.

Tembo passes the whole object to the agent as event context, so your instructions can reference it directly. For example, you could write instructions like *"Fix the issue at the URL provided in the event payload"*.

If you need to transform the payload or fetch extra data before the agent starts, use an [agent post-trigger hook](https://docs.tembo.io/beta/agent-post-trigger-hook). The hook can read `TRIGGER_PAYLOAD` and print Markdown, text, or JSON to standard output; Tembo adds that output to the agent's starting context.

#### Authenticate with a query parameter

Some services only let you configure a URL, not headers. In that case, pass your API key as the `apiKey` query parameter:

```bash theme={null}
curl -X POST "https://api.tembo.io/v1/agents/AGENT_ID/runs?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ticket_id": "SUP-1234"}'
```

> [!WARNING]
>
> URLs can end up in logs and webhook delivery histories. Use the `Authorization` header when the sending service supports it.

#### Follow a run to its session

The agent works in a session that the run creates when it starts. To find that session, use the `runId` from the response.

1. Retrieve the run. You can call this right after you create it:

   ```bash theme={null}
   curl "https://api.tembo.io/v1/agents/AGENT_ID/runs/RUN_ID" \
     -H "Authorization: Bearer YOUR_API_KEY"
   ```

   ```json theme={null}
   {
     "id": "5f0c8d1e-7a42-4c1b-9e3d-2b6a8f4c9d10",
     "sessionId": null,
     "status": "pending",
     "createdAt": "2026-11-11T09:00:00.000Z",
     "updatedAt": "2026-11-11T09:00:00.000Z",
     "durationMs": 0,
     "errorMessage": null
   }
   ```

2. Poll the run until `sessionId` is set:

   | `status` | Meaning |
   | - | - |
   | `pending` | The run is queued or starting. `sessionId` is `null` until the session is created. |
   | `finished` | The run started its session. The agent keeps working in that session. |
   | `failed` | The run couldn't start. `errorMessage` explains why. |

   A `finished` run means the session started, not that the agent's work is done.

3. Retrieve the session to follow the agent's progress:

   ```bash theme={null}
   curl "https://api.tembo.io/v1/sessions/SESSION_ID" \
     -H "Authorization: Bearer YOUR_API_KEY"
   ```

   The `state` flags (`isQueued`, `inProgress`, `isCompleted`, `isFailed`, and `isCancelled`) show where the agent is. `htmlUrl` opens the session in the dashboard.

To see recent runs instead, list the agent's runs, newest first:

```bash theme={null}
curl "https://api.tembo.io/v1/agents/AGENT_ID/runs" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

See [Create an agent run](https://docs.tembo.io/api/v1/agents/create-an-agent-run.md), [Retrieve an agent run](https://docs.tembo.io/api/v1/agents/retrieve-an-agent-run.md), [List agent runs](https://docs.tembo.io/api/v1/agents/list-agent-runs.md), and [Retrieve a session](https://docs.tembo.io/api/v1/sessions/retrieve-a-session.md) for the full API reference.

#### Errors

| Status | Cause |
| - | - |
| `400` | The body isn't a JSON object, or the agent ID isn't a UUID. |
| `401` | The API key is missing, invalid, revoked, or expired. |
| `404` | No agent with that ID exists in the API key's organization. |

## Creating an agent

You can create agents in the dashboard or define them in a repository.

### From a template

![Agent templates](https://mintcdn.com/test-8862363a/_KF7n4fDwDrxMgZe/images/integrations-light.png?fit=max\&auto=format\&n=_KF7n4fDwDrxMgZe\&q=85\&s=cf308a551e35d085a49c48289c6f003e)

1. Go to **Agents** in the [dashboard](https://app.tembo.io)
2. Click **Templates**
3. Pick a template and click **Use template**
4. Customize the instructions and enable

[Browse all templates](https://tembo.io/for)

### From scratch

1. Click **New Agent**
2. Write your instructions
3. Add triggers (schedule and/or event-based)
4. Select [agent harness](#agent-harness)
5. Instruct MCP servers or integrations
6. Optionally select a [project](https://docs.tembo.io/features/projects.md) in run options so runs start from that prepared environment
7. Save and enable

### From a repository

Store an agent's instructions, runtime settings, recurring schedules, and event triggers with the code it works on. Tembo syncs each JSON file directly inside `.tembo/agents/` and creates or updates the corresponding agent in your workspace.

#### Prerequisites

* Connect your GitHub, GitLab, or Bitbucket account to Tembo.
* Activate the repository under **Active Repositories** on the **Settings > Integrations** page.
* Make sure you can merge changes into the repository's default branch.

#### Create a scheduled agent

**1. Create the agent directory**

At the root of your repository, create `.tembo/agents/`.

Agent definitions must be `.json` files directly inside this directory. Nested files and other file types are ignored.

**2. Add an agent definition**

Create a file such as `.tembo/agents/weekly-changelog.json`:

```json theme={null}
{
  "name": "Weekly changelog",
  "prompt": "Summarize the changes merged during the last week and open a pull request that updates the changelog.",
  "schedule": "0 9 * * 1"
}
```

`name` and `prompt` are required. The schedule above runs every Monday at 09:00 UTC.

**3. Merge the definition**

Commit the file and merge it into the repository's default branch. Tembo creates the agent during the next repository sync. Future changes to the file update the same agent.

**4. Verify the agent**

Open **Agents**, select the agent, and confirm its instructions and next scheduled run.

#### Configure multiple schedules

Use `schedules` to run the same agent on more than one cron schedule. Entries can be cron strings or objects with a `cron` property.

```json theme={null}
{
  "name": "Repository maintenance",
  "prompt": "Review the repository for stale dependencies and maintenance work. Open a pull request for safe updates.",
  "schedules": [
    "0 9 * * 1",
    { "cron": "0 12 * * 5" }
  ]
}
```

This example runs at 09:00 every Monday and 12:00 every Friday. Repository-defined schedules use UTC.

> [!NOTE]
>
> Use either `schedule` or `schedules` in one file, not both. You can configure up to 50 schedules for an agent.

#### Configure event triggers

Use `triggers` to start the agent when an event happens in a connected integration.

```json theme={null}
{
  "name": "Pull request reviewer",
  "prompt": "Review the pull request that triggered this run and comment on bugs or risky changes.",
  "triggers": [
    {
      "name": "pull_request.opened",
      "integrationType": "github",
      "filters": {
        "repositories": ["acme/api"],
        "branches": ["main"]
      }
    }
  ]
}
```

This example runs when someone opens a pull request that targets `main` in the `acme/api` repository. Tembo passes the event payload to the agent as context, so your prompt can refer to the pull request, issue, or message that started the run.

| Field | Description |
| - | - |
| `name` | Required. The trigger name, such as `pull_request.opened`. |
| `integrationType` | Required. The integration that sends the event, such as `github`, `slack`, `linear`, or `sentry`. |
| `integrationId` | Optional. The connected integration to use when your workspace has more than one integration of this type. |
| `filters` | Optional. Trigger-specific conditions, such as repositories, branches, or labels. |

Use [List integration triggers](https://docs.tembo.io/api/v1/integrations/list-integration-triggers.md) to find each integration type's trigger names and supported filters. Use [List integrations](https://docs.tembo.io/api/v1/integrations/list-integrations.md) to find an `integrationId`.

Tembo attaches each trigger to your workspace's connected integration of that type. If your workspace has several, Tembo uses the one that hosts the repository, such as the GitHub installation for a GitHub repository. If none of them hosts the repository, set `integrationId`.

> [!NOTE]
>
> Connect the integration before you merge the file. Each trigger name can appear once per agent, and you can configure up to 50 triggers for an agent.

> [!WARNING]
>
> A trigger isn't limited to the repository that contains the agent file. Without a `repositories` filter, `pull_request.opened` starts the agent for pull requests in every active repository connected through that integration.

##### Pull request filters

GitHub's `pull_request.opened` trigger supports these filters:

| Filter | Type | Description |
| - | - | - |
| `repositories` | string array | Only run for pull requests in these repositories, written as `owner/repo`. |
| `branches` | string array | Only run for pull requests that target one of these branches. |
| `labels` | string array | Only run when the pull request has at least one of these labels. |
| `openedBy` | string array | Only run for pull requests opened by one of these GitHub usernames. |
| `draftPrs` | boolean | Also run for draft pull requests. Defaults to `false`. |
| `temboPrs` | boolean | Run for pull requests that Tembo opened. Defaults to `true`. |

Omit `repositories`, `branches`, `labels`, or `openedBy` to match any value. Other triggers support their own filters, which [List integration triggers](https://docs.tembo.io/api/v1/integrations/list-integration-triggers.md) returns.

##### Trigger names

Common trigger names include:

| Integration | `integrationType` | Trigger names |
| - | - | - |
| GitHub | `github` | `pull_request.opened`, `pull_request.ready_for_review`, `pull_request.synchronize`, `pull_request.merged`, `pull_request.closed`, `pull_request.labeled`, `pull_request.review_requested`, `pull_request_review.submitted`, `issues.opened`, `issues.closed`, `issue_comment.created`, `workflow_run.failed`, `workflow_run.completed`, `release.published`, `create` |
| GitLab | `gitlab` | `merge_request.opened`, `merge_request.ready_for_review`, `merge_request.updated`, `merge_request.merged`, `merge_request.closed`, `issue.opened`, `issue.updated`, `issue.closed`, `issue.label_added`, `issue_note.created`, `pipeline.failed`, `ref.created` |
| Bitbucket | `bitbucket` | `pull_request.opened` |
| Linear | `linear` | `Issue.create`, `Issue.update`, `Issue.statusChanged`, `Issue.labelAdded` |
| Sentry | `sentry` | `issue.created` |
| Slack | `slack` | `message.sentInChannel`, `message.reactionAdded` |
| Jira | `atlassian` | `jira:issue_created`, `jira:issue_updated`, `jira:issue_status_changed`, `jira:issue_assigned_to_user`, `jira:issue_added_to_board`, `jira:issue_label_added`, `jira:issue_comment_created` |

Trigger names are case-sensitive. For the complete list, call [List integration triggers](https://docs.tembo.io/api/v1/integrations/list-integration-triggers.md).

#### Configure the runtime

You can keep the agent's execution settings in the same file:

```json theme={null}
{
  "name": "Weekly changelog",
  "prompt": "Summarize the changes merged during the last week and open a pull request that updates the changelog.",
  "model": "codex:gpt-6.1-sol",
  "agentOptions": {
    "reasoningLevel": "high"
  },
  "mcpServers": ["linear"],
  "sandboxSize": "large",
  "projectId": "tembo",
  "artifactType": "PullRequest",
  "schedules": [
    { "cron": "0 9 * * 1" }
  ]
}
```

| Field | Description |
| - | - |
| `model` | Agent harness and model key. See [Models](https://docs.tembo.io/features/models.md) for supported options. `agent` is accepted as an alias, but do not set both. |
| `agentOptions` | Harness-specific options, such as `reasoningLevel`. |
| `mcpServers` | MCP server names that the agent can use. Connect them before the agent runs. |
| `sandboxSize` | VM size: `nano`, `micro`, `small`, `medium`, `large`, `xl`, `xxl`, or `ultra`. |
| `projectId` | A project UUID, or `tembo` to use the base environment. See [Projects](https://docs.tembo.io/features/projects.md). |
| `artifactType` | Expected result: `PullRequest`, `ToolCall`, `Plan`, `Response`, `File`, `Service`, or `Source`. |
| `schedule` | One cron expression. |
| `schedules` | Up to 50 cron strings or objects containing a `cron` property. |
| `triggers` | Up to 50 event triggers. See [Configure event triggers](#configure-event-triggers). |

Omit optional runtime fields to use the existing agent settings. For a new agent, omitted fields use your workspace defaults.

#### How synchronization works

Tembo matches an agent by its `name` within the connected repository. An agent with the same name managed by another repository remains separate.

* Changing the prompt or runtime fields updates the repository's matching agent.
* Changing the configured cron expressions adds and removes schedules to match the file.
* Omitting both `schedule` and `schedules` leaves existing schedules unchanged.
* Setting `"schedules": []` removes all schedules from the agent.
* Changing `triggers` adds, updates, and removes triggers to match the file.
* Omitting `triggers` leaves existing triggers unchanged, including triggers you added in Tembo.
* Setting `"triggers": []` removes all triggers from the agent.
* Disabling the agent in Tembo also keeps newly synced schedules and triggers disabled.
* Removing the JSON file does not delete the agent. Delete or archive the agent from Tembo if you no longer need it.
* Changing `name` creates a different agent instead of renaming the existing one.

#### Troubleshooting

> [accordion] The agent does not appear
>
> Confirm that the repository is active in **Settings > Integrations**, the file is valid JSON with a `.json` extension, and it is directly inside `.tembo/agents/` on the default branch. Repository changes are processed asynchronously, so allow time for the next sync.

> [accordion] The file is skipped
>
> Tembo skips that file if it contains invalid JSON, unknown fields, conflicting fields such as both `schedule` and `schedules`, an unsupported model or runtime option, an inaccessible project, or an invalid or impossible cron expression. Tembo also skips it if a trigger name doesn't exist for its `integrationType`, the trigger filters are invalid, or Tembo can't find a single connected integration for a trigger. Other valid agent files in the directory continue to sync.

> [accordion] A schedule runs at the wrong time
>
> Repository-defined cron schedules use UTC. Convert your desired local time to UTC and account for daylight saving time when you choose the expression.

> [accordion] A removed file still has an agent
>
> Removing a file stops source-controlled updates but does not delete or archive its existing agent. Delete or archive the agent from **Agents**.

## Macros

You can trigger a specific agent on demand from anywhere you can mention `@tembo` by using its macro.

```txt theme={null}
@tembo !<macro-name> <prompt>
```

Tembo routes the request to the agent with that macro and passes the rest of the message as the prompt.

For example, this triggers the agent named `review`:

```txt theme={null}
@tembo !review please review this PR
```

## Beyond code

Agents aren't limited to engineering work. With [MCP servers](https://docs.tembo.io/integrations/mcp.md), agents can work across your entire stack.

| Example | Trigger | What it does |
| - | - | - |
| Daily ARR report | Daily | Pulls revenue data from [Stripe](https://docs.tembo.io/integrations/mcp.md) and posts to [Slack](https://docs.tembo.io/integrations/slack.md) |
| Feature requests from calls | Daily | Scans call transcripts for feature requests and creates [Linear](https://docs.tembo.io/integrations/linear.md) tickets |
| Customer health check | Weekly | Summarizes support tickets, usage trends, and churn signals in [Slack](https://docs.tembo.io/integrations/slack.md) |
| Enrich CRM records | New deal created | Pulls company info and adds context to [Attio](https://docs.tembo.io/integrations/mcp.md) or your CRM |
| Create CRM tickets from Slack | `@tembo` in [Slack](https://docs.tembo.io/integrations/slack.md) | Creates a ticket in your CRM enriched with context from other connected integrations |

Any tool with an [MCP server](https://docs.tembo.io/integrations/mcp.md) can be used as an agent.

You can also do this on-demand from [Slack](https://docs.tembo.io/integrations/slack.md) without setting up an agent:

```
@tembo What's our ARR right now? Check Stripe.
```

```
@tembo Summarize the feature requests from this week's sales calls and create Linear tickets for the top 5.
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.