Build AI Agents

Build production AI agents that connect prompts, tools, sub-agents, data, guardrails, budgets, approvals, and observable execution trees.

Build AI Agents

Agents are the runnable units in PromptRails. An agent packages the prompt logic, model settings, tools, sub-agents, data sources, guardrails, run budget, 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 an agent uses before you run it or change it.

Loading screenshot

What is an Agent?

An agent answers these questions:

• What prompt or graph of steps should run?
• Which model and sampling settings should be used?
• Which tools, sub-agents, data sources, and memory are available?
• Which input and output guardrails should protect the run?
• What budget and approval policy bound the run?
• 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 has exactly two agent types. Pick the simplest shape that matches the job.

Agent

An agent is a single prompt plus optional tools and sub-agents. Use it for classification, extraction, rewriting, Q&A, retrieval-augmented answers, and tool-using assistants. When an agent has sub-agents attached, it acts as a supervisor that can delegate to or hand off to those agents.

Workflow

A workflow is a deterministic graph (DAG) of typed nodes for AI calls, tools, data, conditions, routers, loops, approvals, other agents, and media generation. Use it when the execution path should be explicit, including sequential steps, conditional branches, parallel fan-out, and merges.

Agent Configuration

Configuration lives on the agent version, not on the agent itself. Each version stores:

• A config object that carries only the agent-kind payload — prompt_id for an agent, or nodes for a workflow.
• The version-scoped runtime settings that surround config: model_config (model + sampling), run_budget, approval_policy, cache_timeout, and the attached tools, sub_agents, and guardrails.
• The input_schema and output_schema for the run.

Because model, sampling, budget, approval policy, and tool/sub-agent/guardrail attachments are version-scoped, the linked prompt stays pure content. See Agent Versioning for the config helpers and full field reference, and MCP Tools, Data Sources, Knowledge Sources, and Guardrails for the resources you attach.

Agent Status

Agents move through a simple lifecycle:

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="agent",  # "agent" or "workflow"
)
 
print(f"Agent created: {agent.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: 'agent', // 'agent' or 'workflow'
})
 
console.log(`Agent created: ${agent.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.current_version)

client.agents.update(
    agent_id="your-agent-id",
    name="Updated Bot Name",
    description="Updated description",
    labels=["support", "production"],
)

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"},
)
 
print(f"Status: {result.status}")
print(f"Output: {result.output}")
print(f"Cost: ${result.cost:.6f}")
print(f"Trace: {result.trace_id}")

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

client.agents.update(
    agent_id="your-agent-id",
    labels=["production", "customer-facing", "v2"],
)

Related Topics

• Agent Versioning — Version management, model config, budgets, and tool/sub-agent attachments
• Prompts — Prompt templates used by agents
• Guardrails — Input/output safety scanners
• MCP Tools — External tools available to agents
• Executions — Execution trees, lifecycle, and monitoring