Agents

Understand what an agent is, what it owns, and how it connects prompts, tools, data, guardrails, memory, and approvals.

Agents are the runnable units in PromptRails. An agent packages the prompt logic, model settings, tools, data sources, guardrails, memory, and approval behavior needed to handle one job.

In the product, agents live in Studio next to the prompts, data sources, and tools they depend on. That makes it easier to see what a workflow uses before you run it or change it.

Loading screenshot

What is an Agent?

An agent answers these questions:

• What prompt or sequence of prompts should run?
• Which model settings should be used?
• Which tools, data sources, and memory are available?
• Which input and output guardrails should protect the run?
• Does the run need human approval before continuing?
• What input and output shape should the caller expect?

Agents belong to one workspace. In the UI, you normally work with names; in SDKs and APIs, you pass the agent ID.

Agent Types

PromptRails supports five agent types. Pick the simplest shape that matches the job.

Simple

A simple agent runs one prompt against one model. Use it for classification, extraction, rewriting, Q&A, and other single-step tasks.

Chain

A chain agent runs prompts in order. The output from one step becomes input to the next, which is useful when a workflow needs drafting, review, and final formatting as separate stages.

Multi-Agent

A multi-agent configuration runs specialized agents in parallel or routes work between them. Use it when different parts of the task need different expertise.

Workflow

A workflow agent uses a graph of steps with branches. Use it when business logic determines whether to call a prompt, query data, invoke a tool, ask for approval, or stop.

Composite

A composite agent combines other agents into a larger workflow. Use it only when the flow is clearer as smaller reusable agents stitched together.

Agent Configuration

Each agent version stores a config that matches the agent type. The SDKs expose type-specific helpers, so you choose the config for a simple, chain, multi-agent, workflow, or composite agent and the SDK sends the correct shape.

Common fields across all variants:

Type-specific fields:

Tools, data sources, knowledge sources, and guardrails are attached to the agent or prompt rather than buried inside the config object. See MCP Tools, Data Sources, Knowledge Sources, and Guardrails.

See Agent Versioning for SDK examples.

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

Create agents from Studio when you are shaping the workflow with product, operations, or security teammates. Use the API or SDK when agent creation is part of an internal platform workflow.

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

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}`)

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

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

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

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

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

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