Agents

An agent is a name, a system prompt, a capability model and optional connectors or a workflow graph. A run is one execution of it. Each step of a run is journaled, so a run that crashes resumes where it stopped instead of starting over. The full picture of a run is on How PAL Runtime works.

Create an agent

Way	How
AI-assisted	Dashboard, Agents > New agent > Describe with AI. Describe the job; PAL drafts the configuration and prompt, and you edit before anything is created
Manual	Fill in name (lowercase, hyphens), description, system prompt, model capability and connectors
Template	The dashboard offers ready-made agents; the CLI scaffolds from seven starters: `basic`, `research`, `tool-use`, `connector`, `personal`, `scheduled`, `approval`

pal init my-agent --template research   # scaffold from a starter

Over REST, GET /v1/agents/templates lists templates, POST /v1/agents/from-template creates an agent from one (agents:write), and GET /v1/agents/{name}/setup reports which connectors or channels the agent still needs.

Configure it

The system prompt does most of the work. State the role, the steps and what to do on failure:

You are a research assistant. When given a topic:
1. Generate 3-5 search queries
2. Search the web for each query
3. Synthesize findings into a structured report with citations

If you cannot find reliable information, say so rather than making things up.

The model field takes a capability (auto, reasoning-large, …), not a vendor model. Pin a cheap one on a high-volume agent and a stronger one where quality matters. Allowed values, failover and validation: Models and routing.

Test and run

Every agent has a Chat tab in the dashboard. It shows streaming output and each step as it executes (timing, model, tokens); the Runs tab has the full event trace. From the CLI:

pal runs create --agent my-agent \
  --input '{"topic": "quantum computing"}' \
  --stream                              # stream run events after creation

Trigger	See
Dashboard or `pal runs create --agent <name>`	above
`POST /v1/runs` with `agentName` in the body	REST API
Cron	Scheduling
Signed webhook	Triggers
WhatsApp, Slack, Telegram, webchat	Set up PAL

API keys need agents:write to create or update agents and runs:execute to start runs.

Run states

A run is queued, running, paused (waiting on an approval, takeover or signal), succeeded, failed (a step failed after its retries) or cancelled. A run that crashes mid-step is picked up by the recovery sweep; completed workflow steps are skipped, not re-run. Side effects carry an idempotency key derived from run ID, step ID and attempt, so a replay does not repeat them. See Durable execution for the diagram and the details.

Workflow tool nodes

A tool node in a saved workflow graph really executes, or the step fails. There is no simulated success.

Tool	Runs
`web_search`	In the control plane, via the tenant’s Anthropic key (OpenAI search-preview as fallback). Its model spend is metered like an ai-step
Any other name	In the run’s microVM through the runtime-manager. The in-VM harness serves `shell_exec`, `http_fetch`, `read_file`, `write_file`, `list_dir`

A sandbox tool’s output is { "tool_name": ..., "result": ... }. When no runtime-manager is reachable from the control plane (for example the stub scheduler in dev), the step fails with tool runtime unavailable: "shell_exec" needs the microVM runtime and none is wired. Only web_search works without a runtime.

Each sandbox tool call carries the key hex(sha256("runID|stepID|attempt")), so a retry of the same attempt dedups at the manager. Inside a loop the stepID includes the iteration, <loopNodeId>[<i>]/<nodeId>, so each iteration has its own key.

toolLimits on the agent’s budget are checked before dispatch and counted after. A hard-fail budget fails the step with budget limit exceeded: tool "web_search" budget exhausted (50/50 today). See Budgets.