# Agents

> Learn about PromptRails agents, the five agent types, configuration options, and how to create and manage AI agents.

Source: https://0.0.0.0:8080/docs/agents

Agents are the core building blocks of PromptRails. An agent encapsulates an AI execution strategy, combining prompts, tools, data sources, guardrails, and memory into a single deployable unit.

## What is an Agent?

An agent defines how an AI task is executed. It specifies:

- Which prompts to use and in what order
- Which LLM model to call
- What tools are available for the agent to invoke
- What guardrails to apply on input and output
- How to handle multi-step reasoning, chaining, or orchestration
- Input and output schemas for structured data handling

Agents are workspace-scoped and identified by KSUID (K-Sortable Unique Identifiers).

## Agent Types

PromptRails supports five agent types, each implementing a different execution strategy.

### Simple

A simple agent executes a single prompt against an LLM. This is the most straightforward agent type, suitable for question-answering, text generation, classification, and other single-turn tasks.

```
Input -> Prompt Rendering -> LLM Call -> Output
```

### Chain

A chain agent executes multiple prompts sequentially, where the output of one step becomes the input for the next. Use chains for multi-step reasoning, data transformation pipelines, or tasks that require intermediate processing.

```
Input -> Prompt 1 -> LLM -> Prompt 2 -> LLM -> ... -> Output
```

### Multi-Agent

A multi-agent configuration runs multiple agents in parallel or routes between them based on the input. This is useful for ensemble approaches, specialized sub-agents, or tasks that benefit from multiple perspectives.

```
Input -> [Agent A, Agent B, Agent C] -> Aggregation -> Output
```

### Workflow

A workflow agent defines a directed graph of steps with conditional branching. Each step can be a prompt execution, tool call, data source query, or sub-agent invocation. Workflow agents support complex business logic with decision points.

```
Input -> Step 1 -> Condition -> Step 2a or Step 2b -> ... -> Output
```

### Composite

A composite agent combines multiple agent types into a single higher-level agent. It can orchestrate chains, workflows, and simple agents together, enabling the most complex execution patterns.

## Agent Configuration

Each agent version carries a `config` object whose shape is a
**typed discriminated union** keyed on the agent type — one of
`SimpleAgentConfig`, `ChainAgentConfig`, `MultiAgentConfig`,
`WorkflowAgentConfig`, or `CompositeAgentConfig`. The official SDKs
expose each variant as a dedicated type; callers pick the one that
matches the agent's type, and the SDK emits the `type` discriminator
automatically.

Common fields across all variants:

| Field                      | Description                                                   |
| -------------------------- | ------------------------------------------------------------- |
| `temperature`              | Sampling temperature (0.0 to 1.0). Simple agent only.         |
| `max_tokens`               | Maximum tokens in the LLM response. Simple agent only.        |
| `llm_model_id`             | LLM model identifier. Simple agent only.                      |
| `approval_required`        | Whether execution pauses for human approval (simple / chain). |
| `approval_checkpoint_name` | Name of the approval checkpoint (simple / chain).             |

Type-specific fields:

| Agent type    | Config field                            |
| ------------- | --------------------------------------- |
| `simple`      | `prompt_id` — one prompt per execution  |
| `chain`       | `prompt_ids: PromptLink[]` — sequential |
| `multi_agent` | `prompt_ids: PromptLink[]` — parallel   |
| `workflow`    | `nodes: WorkflowNode[]` — DAG           |
| `composite`   | `steps: CompositeStep[]` — sub-agents   |

Tools, data sources, guardrails, and memory are attached to the agent
itself (or per-prompt) rather than via the config object — see
[MCP Tools](/docs/mcp-tools), [Guardrails](/docs/guardrails), and
[Memory](/docs/memory).

See [Agent Versioning](/docs/agent-versioning#creating-a-version) for
typed examples in all three SDKs.

## Agent Status

Agents have two lifecycle states:

| Status     | Description                                              |
| ---------- | -------------------------------------------------------- |
| `active`   | The agent is available for execution                     |
| `archived` | The agent is hidden from listings and cannot be executed |

Archiving an agent is a soft operation -- the agent and its versions are preserved and can be restored.

## Creating an Agent

**Python SDK**

```python
from promptrails import PromptRails

client = PromptRails(api_key="your-api-key")

agent = client.agents.create(
    name="Customer Support Bot",
    description="Handles customer inquiries about products and orders",
    type="simple",
    labels=["support", "production"]
)

print(f"Agent created: {agent['data']['id']}")
```

**JavaScript SDK**

```typescript
import { PromptRails } from '@promptrails/sdk'

const client = new PromptRails({ apiKey: 'your-api-key' })

const agent = await client.agents.create({
  name: 'Customer Support Bot',
  description: 'Handles customer inquiries about products and orders',
  type: 'simple',
  labels: ['support', 'production'],
})

console.log(`Agent created: ${agent.data.id}`)
```

## Managing Agents

### List Agents

```python
agents = client.agents.list(page=1, limit=20)
for agent in agents["data"]:
    print(f"{agent['name']} ({agent['type']}) - {agent['status']}")
```

### Get Agent Details

```python
agent = client.agents.get(agent_id="your-agent-id")
print(agent["data"]["current_version"])
```

### Update an Agent

```python
client.agents.update(
    agent_id="your-agent-id",
    name="Updated Bot Name",
    description="Updated description"
)
```

### Archive an Agent

```python
client.agents.update(
    agent_id="your-agent-id",
    status="archived"
)
```

## Executing an Agent

Execute an agent by providing input that matches the agent's input schema:

```python
result = client.agents.execute(
    agent_id="your-agent-id",
    input={
        "message": "I need help with my order #12345"
    },
    metadata={
        "user_id": "customer-456",
        "channel": "web"
    }
)

print(f"Status: {result['data']['status']}")
print(f"Output: {result['data']['output']}")
print(f"Cost: ${result['data']['cost']:.6f}")
print(f"Duration: {result['data']['duration_ms']}ms")
```

## Input and Output Schemas

Agent versions can define JSON schemas for structured input and output validation:

```json
{
  "input_schema": {
    "type": "object",
    "properties": {
      "message": { "type": "string" },
      "language": { "type": "string", "default": "en" }
    },
    "required": ["message"]
  },
  "output_schema": {
    "type": "object",
    "properties": {
      "response": { "type": "string" },
      "confidence": { "type": "number" }
    }
  }
}
```

Input schemas are validated before execution. Output schemas define the expected structure of the agent's response.

## Labels

Agents support arbitrary string labels for organization and filtering:

```python
agent = client.agents.create(
    name="My Agent",
    type="simple",
    labels=["production", "customer-facing", "v2"]
)
```

## Related Topics

- [Agent Versioning](/docs/agent-versioning) -- Version management for agents
- [Prompts](/docs/prompts) -- Prompt templates used by agents
- [Guardrails](/docs/guardrails) -- Input/output safety scanners
- [MCP Tools](/docs/mcp-tools) -- External tools available to agents
- [Executions](/docs/executions) -- Execution lifecycle and monitoring