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

# Agents

> Understanding Agents and how they run

# Agents

**Agents** are autonomous AI entities that can execute tasks and use tools. Each agent belongs to an **organization** and, optionally, to an **AgentTemplate** that seeds its initial configuration.

## Agent Properties

| Field              | Description                                                                                                       |
| ------------------ | ----------------------------------------------------------------------------------------------------------------- |
| `name`             | Human-readable name                                                                                               |
| `organization`     | Owning org (auto-filled from the caller's API key / token)                                                        |
| `template`         | The [AgentTemplate](/concepts/templates) this agent was stamped from (nullable for ad-hoc agents)                 |
| `purpose`          | `production` / `eval` / `dev`. Only `production` agents are woken by the `wake_agents` cron.                      |
| `tags`             | Free-form string labels (e.g. `scenario:group-lunch-memory`, `git-ref:feature/x`)                                 |
| `model`            | LLM model (e.g., `claude-sonnet-4-5`, `gpt-4o`). Copied from the template's `default_model` at creation if blank. |
| `reasoning_effort` | `''` (model default) / `minimal` / `low` / `medium` / `high` / `xhigh` / `max`                                    |
| `system_prompt`    | Instructions (copied from template's `system_prompt` at creation if blank)                                        |
| `timezone`         | Agent's timezone for time-aware operations                                                                        |
| `max_turns`        | Maximum iterations per run (default: 50)                                                                          |
| `status`           | Current state: `running` / `sleeping` / `archived`                                                                |
| `sleep_until`      | When the agent will wake up (if sleeping)                                                                         |
| `adapters`         | Tools available to this agent (seeded from the template's adapter set)                                            |

## Creating an Agent

Usually you create an agent from a template — the agent snapshots the template's `system_prompt`, `default_model`, adapter set, and per-adapter config at creation.

```bash theme={null}
curl -X POST https://api.bedrock.orinlabs.org/api/cloud/agents/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Agent",
    "template": "TEMPLATE_ID",
    "timezone": "America/New_York"
  }'
```

You can override any field at creation time (e.g., specify a custom `model`, `system_prompt`, or `adapters` array). Ad-hoc agents without a template are allowed too — pass `template: null` and provide `model` + `system_prompt` + `adapters` explicitly.

<Note>
  If `model` or `system_prompt` are blank at creation and a template is attached, the template's values are copied in. Template edits after that don't retroactively change the agent.
</Note>

### Tagging Agents

Tags are free-form string labels. Useful for filtering in the portal — e.g., `git-ref:feature/x` on eval agents, or `cohort:beta` on production agents.

```bash theme={null}
curl -X POST https://api.bedrock.orinlabs.org/api/cloud/agents/AGENT_ID/tags/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tag": "cohort:beta"}'
```

```bash theme={null}
curl -X DELETE https://api.bedrock.orinlabs.org/api/cloud/agents/AGENT_ID/tags/cohort:beta/ \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Both endpoints are idempotent — the POST returns `200` if the tag already existed, `201` if it was created.

## Running an Agent

Wake an agent to start execution:

```bash theme={null}
curl -X POST https://api.bedrock.orinlabs.org/api/cloud/agents/AGENT_ID/run/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"wakeup": true}'
```

### What Happens During a Run

Every `run_agent` invocation spawns an isolated `bedrock-harness` subprocess (pinned to the template's `harness_git_ref`, or latest `main` if unset). The harness drives the loop and streams spans back to Bedrock over HTTP; a `HarnessRun` row links the subprocess to the resulting `Trace`.

1. **Status Change**: Agent transitions to `RUNNING`
2. **Runtime Loop** (up to `max_turns` iterations):
   * Build prompt with system instructions and adapter state
   * Call LLM with available tools
   * Process any tool calls
3. **Sleep**: Agent calls `sleep` tool or hits max turns

### The Runtime Loop

1. Build prompt with tools and adapter state
2. Call LLM
3. Process tool calls
4. Check if should continue — if yes, go back to step 1; if no (sleep called), exit

## Built-in Default Tools

Every agent has access to these tools regardless of adapters:

| Tool           | Description                                                    |
| -------------- | -------------------------------------------------------------- |
| `sleep`        | Sleep until a specified datetime (with checklist verification) |
| `wait`         | Pause briefly (max 30 seconds)                                 |
| `set_timezone` | Update the agent's timezone                                    |

### Sleep Tool

Agents must call `sleep` to end their run gracefully. Before sleeping, the agent must verify a checklist of conditions:

```json theme={null}
{
  "name": "sleep",
  "arguments": {
    "all_tasks_completed": true,
    "no_pending_background_tasks": true,
    "until": "2024-01-15T14:00:00Z"
  }
}
```

| Parameter                     | Description                                                                                                                                                                                                |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `all_tasks_completed`         | Confirm you've done everything you can on your tasks right now. True if tasks are complete OR you MUST wait on something external with nothing more to do. False if there's still work you could be doing. |
| `no_pending_background_tasks` | Confirm there's nothing else you could be working on. False if you could improve your work, make it more comprehensive, or handle other responsibilities.                                                  |
| `until`                       | ISO 8601 datetime to sleep until                                                                                                                                                                           |

<Note>
  Sleeping to wait on the user is usually an indication that more work should be done. Agents should only sleep when they MUST wait on something external, not when they simply need user input.
</Note>

If any checklist item is `false`, the sleep will be rejected and the agent must address the issue before sleeping.

If an agent doesn't call `sleep` and hits `max_turns`, it's automatically put to sleep for 1 hour.

## Stopping an Agent

Force-stop a running agent:

```bash theme={null}
curl -X POST https://api.bedrock.orinlabs.org/api/cloud/agents/AGENT_ID/stop/ \
  -H "Authorization: Bearer YOUR_API_KEY"
```

This immediately transitions the agent to `SLEEPING` status.

## Agent State

Agents using built-in adapters have persistent state:

| State             | Description                                                                                                                                                                                                   |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Contacts**      | Phone book of people the agent knows                                                                                                                                                                          |
| **Documents**     | Text documents for reference. Each document has a `kind`: `note` (ephemeral scratchpad) or `skill` (curated knowledge — facts or SOPs — that can be promoted into template adapter config for future agents). |
| **Projects**      | Hierarchical project tracking                                                                                                                                                                                 |
| **Notifications** | Pending notifications and reminders                                                                                                                                                                           |
| **Messages**      | SMS/Email/MMS conversation history                                                                                                                                                                            |

This state persists across runs and is private to each agent.

## Supported Models

Bedrock supports models from:

**Anthropic (Claude)**:

* `claude-sonnet-4-5`
* `claude-opus-4`
* `claude-haiku-4-5`

**OpenAI**:

* `gpt-4o`
* `gpt-4o-mini`
* `gpt-4-turbo`

Claude models get automatic access to web search capabilities.

## Usage Tracking

Get usage statistics for an agent:

```bash theme={null}
curl -X GET "https://api.bedrock.orinlabs.org/api/cloud/agents/AGENT_ID/usage/?start_date=2024-01-01T00:00:00Z" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Response:

```json theme={null}
{
  "agent_id": "agent-uuid",
  "agent_name": "Support Agent",
  "input_tokens": 45000,
  "output_tokens": 12000,
  "cached_tokens": 30000,
  "total_cost_usd": 0.85,
  "llm_calls": 150,
  "model_breakdown": {
    "claude-sonnet-4": {
      "input_tokens": 45000,
      "output_tokens": 12000,
      "total_cost_usd": 0.85,
      "llm_calls": 150
    }
  }
}
```

## Wakeup Message

When an agent wakes up, it receives this instruction:

> You are being woken up from sleep. Gather information from your tools to determine what to do next. Check every tool that stores information (like any tool with 'list' in the name) to re-ground yourself.

This prompts agents to check for new messages, tasks, etc. before taking action.

## Example: Complete Agent Lifecycle

```python theme={null}
import requests

API_KEY = "your-api-key"
BASE_URL = "https://api.bedrock.orinlabs.org"
headers = {"Authorization": f"Bearer {API_KEY}"}

# 1. Create an agent from a template
agent = requests.post(
    f"{BASE_URL}/api/cloud/agents/",
    headers=headers,
    json={
        "name": "Task Manager",
        "template": "TEMPLATE_ID",
    }
).json()

# 2. Run the agent
requests.post(
    f"{BASE_URL}/api/cloud/agents/{agent['id']}/run/",
    headers=headers,
    json={"wakeup": True}
)

# 3. Check status
status = requests.get(
    f"{BASE_URL}/api/cloud/agents/{agent['id']}/",
    headers=headers
).json()
print(f"Agent status: {status['status']}")

# 4. View execution traces
traces = requests.get(
    f"{BASE_URL}/api/tracing/traces/list/",
    headers=headers,
    params={"agent": agent["id"]},
).json()
```