Agents

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

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:

Type-specific fields:

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

See Agent Versioning for typed examples in all three SDKs.

Agent Status

Agents have two lifecycle states:

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

Creating an Agent

Python SDK

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

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

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

Get Agent Details

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

Update an Agent

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

Archive an Agent

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:

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:

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

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

Related Topics

• Agent Versioning -- Version management for agents
• Prompts -- Prompt templates used by agents
• Guardrails -- Input/output safety scanners
• MCP Tools -- External tools available to agents
• Executions -- Execution lifecycle and monitoring