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

# Templates

> Blueprints for creating agents: prompt, model, adapters, tool-call secret

# Templates

An **AgentTemplate** is a named blueprint for creating agents. Its configuration — system prompt, default model, adapter set with per-adapter config, harness git ref, tool-call secret — is copied onto every new agent at creation time. Template edits don't retroactively change existing agents; each agent keeps its own snapshot.

Think of a template like a Docker image: you author it once and deploy as many agent instances as you need.

## What's in a Template?

| Field                       | Description                                                                         |
| --------------------------- | ----------------------------------------------------------------------------------- |
| `name`                      | Human-readable name (unique per organization)                                       |
| `description`               | Optional short summary                                                              |
| `system_prompt`             | Default instructions stamped onto new agents                                        |
| `default_model`             | Default LLM model for new agents (e.g., `claude-sonnet-4-5`)                        |
| `default_reasoning_effort`  | `''` (model default) / `minimal` / `low` / `medium` / `high` / `xhigh` / `max`      |
| `thinking_max_tokens`       | Max output tokens per LLM call (overrides the effort-based default on Claude)       |
| `max_turns`                 | Maximum iterations per run (default `50`; `0` = unlimited)                          |
| `harness_git_ref`           | Branch / tag / SHA of `bedrock-harness` to run. Blank = latest `main`.              |
| `agent_created_webhook_url` | POSTed with agent + contact details when a new agent auto-spawns from this template |
| `tool_call_secret`          | Sent as `X-Agent-Secret` on external tool webhooks                                  |

The template also owns a set of **AdapterConfig** rows (one per enabled adapter) that define tool integrations.

## Creating a Template

```bash theme={null}
curl -X POST https://api.bedrock.orinlabs.org/api/templates/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Support Bot",
    "description": "Triage + reply to inbound customer questions",
    "system_prompt": "You are a helpful customer support agent for Acme Corp.",
    "default_model": "claude-sonnet-4-5",
    "max_turns": 50
  }'
```

Response:

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "organization": "org-uuid",
  "name": "Customer Support Bot",
  "description": "Triage + reply to inbound customer questions",
  "system_prompt": "You are a helpful customer support agent for Acme Corp.",
  "default_model": "claude-sonnet-4-5",
  "default_reasoning_effort": "",
  "thinking_max_tokens": null,
  "max_turns": 50,
  "harness_git_ref": "",
  "agent_created_webhook_url": "",
  "tool_call_secret": "",
  "created_at": "2026-01-15T10:30:00Z"
}
```

## LLM Provider Configuration

LLM provider keys live on the **organization**, not the template — every template in the org shares the same `openai_api_key` / `anthropic_api_key`:

```bash theme={null}
curl -X PATCH https://api.bedrock.orinlabs.org/api/organizations/organizations/ORG_ID/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "openai_api_key": "sk-...",
    "anthropic_api_key": "sk-ant-..."
  }'
```

If unset, Bedrock falls back to the `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` environment variables. See [Organizations](/concepts/organizations) for details.

## System Prompt

The template's `system_prompt` is copied onto each new agent created from the template. Agents can override it with their own `system_prompt` for specialized behavior.

```json theme={null}
{
  "system_prompt": "You are an AI assistant for Acme Corp.\n\nKey responsibilities:\n- Answer customer questions about our products\n- Help troubleshoot common issues\n- Escalate complex problems to human support\n\nTone: Professional but friendly. Never make up information."
}
```

<Note>
  Template edits never retroactively change agents. Update the template first, then create a new agent (or manually update an existing one).
</Note>

## Attaching Adapters

Adapters are attached to a template via **AdapterConfig** rows. Each row couples an adapter to the configuration needed to use it (phone numbers, API keys, etc.).

```bash theme={null}
curl -X POST https://api.bedrock.orinlabs.org/api/toolbox/adapter-configs/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "adapter": "SMS_ADAPTER_ID",
    "template": "TEMPLATE_ID",
    "config": { "phone_number": "+15551234567" }
  }'
```

The `config` payload is validated against the adapter's `config_schema`. Adapters with no config (Contacts, Projects, Documents, Notifications) can be attached by creating an `AdapterConfig` with an empty `config`.

See [Adapters](/concepts/adapters) for per-adapter schemas.

## Deploying Agents

Create agents against a template:

```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": "Alice'\''s Assistant",
    "template": "TEMPLATE_ID",
    "timezone": "America/New_York"
  }'
```

On creation, the agent:

1. Copies `system_prompt` and `default_model` onto itself
2. Adds every adapter referenced by the template's `AdapterConfig` rows to its own `adapters` set
3. Snapshots each `AdapterConfig.config` into a matching `AgentAdapterConfig` row
4. Runs adapter-specific seed hooks (for example, Documents seeds curated "skill" documents onto the new agent)

From then on, the agent is self-contained — template edits don't modify it.

## Tool-Call Secret

The `tool_call_secret` is sent as the `X-Agent-Secret` header on every webhook tool call made by agents created from this template. Set it so your custom adapter handlers can verify requests came from Bedrock.

```bash theme={null}
curl -X PATCH https://api.bedrock.orinlabs.org/api/templates/TEMPLATE_ID/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tool_call_secret": "a-strong-random-secret"}'
```

See [Custom Adapters](/concepts/custom-adapters) for how to verify the secret on your side.

## Harness Git Ref

Every agent run spawns an isolated `bedrock-harness` subprocess pinned to the template's `harness_git_ref`. Blank means latest `main` at dispatch time. Pin this when you want to freeze the runtime — for example, before a fleet-wide rollback:

```bash theme={null}
curl -X PATCH https://api.bedrock.orinlabs.org/api/templates/TEMPLATE_ID/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"harness_git_ref": "v1.4.2"}'
```

## Template → Agent Hierarchy

* **Organization**
  * **Template** (blueprint)
    * **Agents** (snapshots of the template — memory, state, adapter configs are per-agent)

## API Summary

| Method          | Endpoint               | Description     |
| --------------- | ---------------------- | --------------- |
| `GET`           | `/api/templates/`      | List templates  |
| `POST`          | `/api/templates/`      | Create template |
| `GET`           | `/api/templates/{id}/` | Get template    |
| `PUT` / `PATCH` | `/api/templates/{id}/` | Update template |
| `DELETE`        | `/api/templates/{id}/` | Delete template |

## Best Practices

<CardGroup cols={2}>
  <Card title="One Template per Use Case" icon="layer-group">
    Create separate templates for each distinct agent archetype or environment.
  </Card>

  <Card title="Descriptive System Prompts" icon="file-lines">
    Write clear system prompts that define expected behavior.
  </Card>

  <Card title="Pin Harness on Rollback" icon="code-branch">
    Pin `harness_git_ref` to a known-good tag when stabilizing.
  </Card>

  <Card title="Configure Tool Secret" icon="lock">
    Set `tool_call_secret` if using webhook-based tools.
  </Card>
</CardGroup>