Agents

Agents are autonomous AI entities that can execute tasks, use tools, and maintain persistent memory. Each agent belongs to a Product and runs independently.

Agent Properties

Field	Description
`name`	Human-readable name
`model`	LLM model (e.g., `claude-sonnet-4`, `gpt-4o`)
`system_prompt`	Instructions (inherits from product if not set)
`timezone`	Agent’s timezone for time-aware operations
`max_turns`	Maximum iterations per run (default: 50)
`status`	Current state: `running` or `sleeping`
`sleep_until`	When the agent will wake up (if sleeping)
`adapters`	Tools available to this agent

Creating an Agent

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",
    "model": "claude-sonnet-4",
    "system_prompt": "You are a helpful customer support agent.",
    "timezone": "America/New_York",
    "max_turns": 50,
    "adapters": ["Contacts", "SMS", "Projects"]
  }'

If model isn’t specified, the agent uses the product’s default_model. If system_prompt isn’t specified, it inherits from the product.

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

Memory Update: Summaries are refreshed from recent messages
Status Change: Agent transitions to RUNNING
Runtime Loop (up to max_turns iterations):
- Build prompt with system instructions + memory context
- Call LLM with available tools
- Process any tool calls
- Log messages to memory
Sleep: Agent calls sleep tool or hits max turns

The Runtime Loop

┌─────────────────────────────────────────────┐
│              Agent Runtime                   │
├─────────────────────────────────────────────┤
│  1. Load memory context (summaries)          │
│  2. Build prompt with tools                  │
│  3. Call LLM                                 │
│  4. Process tool calls                       │
│  5. Log to memory                            │
│  6. Check if should continue                 │
│     └── If yes, go to step 3                │
│     └── 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 Memory

Each agent has its own persistent memory that maintains conversation history across runs. Memory is automatically summarized into hierarchical levels:

Messages → 5-min summaries → Hourly → Daily → Weekly → Monthly

This allows agents to maintain long-term context without hitting token limits.

Reset Memory

Clear an agent’s memory completely:

curl -X POST https://api.bedrock.orinlabs.org/api/cloud/agents/AGENT_ID/reset-memory/ \
  -H "Authorization: Bearer YOUR_API_KEY"

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
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
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
agent = requests.post(
    f"{BASE_URL}/api/cloud/agents/",
    headers=headers,
    json={
        "name": "Task Manager",
        "model": "claude-sonnet-4",
        "adapters": ["Contacts", "Projects", "SMS"]
    }
).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/?agent={agent['id']}",
    headers=headers
).json()

Get Started

Concepts

Agents

Agents

Agent Properties

Creating an Agent

Running an Agent

What Happens During a Run

The Runtime Loop

Built-in Default Tools

Sleep Tool

Stopping an Agent

Agent Memory

Reset Memory

Agent State

Supported Models

Usage Tracking

Wakeup Message

Example: Complete Agent Lifecycle

Get Started

Concepts

​Agents

​Agent Properties

​Creating an Agent

​Running an Agent

​What Happens During a Run

​The Runtime Loop

​Built-in Default Tools

​Sleep Tool

​Stopping an Agent

​Agent Memory

​Reset Memory

​Agent State

​Supported Models

​Usage Tracking

​Wakeup Message

​Example: Complete Agent Lifecycle

Agents

Agent Properties

Creating an Agent

Running an Agent

What Happens During a Run

The Runtime Loop

Built-in Default Tools

Sleep Tool

Stopping an Agent

Agent Memory

Reset Memory

Agent State

Supported Models

Usage Tracking

Wakeup Message

Example: Complete Agent Lifecycle