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 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.

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.

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.

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.

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"}'

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:

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.

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

The Runtime Loop

Build prompt with tools and adapter state
Call LLM
Process tool calls
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:

{
  "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

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.

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:

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:

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:

{
  "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

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()

​Agents

​Agent Properties

​Creating an Agent

​Tagging Agents

​Running an Agent

​What Happens During a Run

​The Runtime Loop

​Built-in Default Tools

​Sleep Tool

​Stopping an Agent

​Agent State

​Supported Models

​Usage Tracking

​Wakeup Message

​Example: Complete Agent Lifecycle

Agents

Agent Properties

Creating an Agent

Tagging Agents

Running an Agent

What Happens During a Run

The Runtime Loop

Built-in Default Tools

Sleep Tool

Stopping an Agent

Agent State

Supported Models

Usage Tracking

Wakeup Message

Example: Complete Agent Lifecycle