Agents

Agents are autonomous, multi-turn AI systems that use capabilities and tasks to accomplish goals. Instead of making multiple LLM calls, agents write JavaScript code that executes in a sandbox, calling SDK functions.

What is an Agent?

Agents:

Execute multiple operations in a single LLM call
Use JavaScript code instead of traditional tool calls
Maintain state across turns via a REPL
Access capabilities like web, memory, databases, and APIs
Can call tasks for specialized operations

How Agents Work

Traditional Approach:
  LLM → tool → LLM → tool → LLM → tool (5-10 round trips)

runpiper Approach:
  LLM → JavaScript code block (1 round trip)

Result: 97% cost reduction, 97% latency reduction for mechanical operations.

Agent Configuration

# agents/researcher.toml
[agent]
name = "researcher"
goal = "Research topics and compile findings"

[agent.capabilities]
web = true
memory = true
tasks = ["summarize", "extract"]

Required Fields

Field	Description
`agent.name`	Unique agent name
`agent.goal`	Description of what the agent should accomplish
`agent.capabilities`	Capabilities the agent can use

Capabilities Section

[agent.capabilities]
# Built-in capabilities
web = true
memory = true

# Configured capabilities (by name)
database = "my-database"
api = "acme-api"

# Tasks the agent can call
tasks = ["summarize", "extract", "translate"]

Agent Tools

Agents have access to three tools:

Tool	Purpose
`plan`	Break down goal into steps, track progress
`execute_code`	Run JavaScript with SDK access
`done`	Signal completion with final answer

Example Agent Loop

Turn 1 - Plan:
  tool: plan
  args: { steps: ["Search for info", "Analyze results", "Compile summary"] }

Turn 2 - Execute:
  tool: execute_code
  args: { code: "const results = web.search('...'); return results;" }

Turn 3 - Execute:
  tool: execute_code
  args: { code: "const summary = tasks.summarize({text: ...}); return summary;" }

Turn 4 - Done:
  tool: done
  args: { answer: "Here's what I found: ..." }

SDK Access

The agent’s SDK is generated from the capabilities configuration:

Built-in SDK

// Web search and fetch
const results = web.search("AI news");
const page = web.fetch(results[0].url);

// Memory operations
memory.add("Important fact", { category: "facts" });
const related = memory.search("facts");
memory.set("key", "value");
const value = memory.get("key");

Database SDK

// Query database
const users = db.query("SELECT * FROM users WHERE active = $1", [true]);
db.execute("INSERT INTO logs (message) VALUES ($1)", ["Done"]);

Custom HTTP SDK

// Call external APIs
const users = http.acme.get("/users");
const response = http.api.post("/endpoint", { data: "value" });

Task SDK

// Call other tasks
const summary = tasks.summarize({ text: "Long text..." });
const extracted = tasks.extract({ text: "...", fields: ["name", "email"] });

Persistent Sessions

Variables persist across turns within a session:

// Turn 1
const results = web.search("wasm performance");

// Turn 2 - results still in scope
const page = web.fetch(results[0].url);

// Turn 3 - both still available
memory.add("Found: " + page.title);

Performance: ~20µs per turn with same context reuse.

Agent Examples

Research Agent

[agent]
name = "researcher"
goal = "Research topics online and compile comprehensive findings"

[agent.capabilities]
web = true
memory = true
tasks = ["summarize"]

Data Analyst Agent

[agent]
name = "analyst"
goal = "Query databases, analyze data, and generate reports"

[agent.capabilities]
web = true
memory = true
database = "my-database"
tasks = ["summarize", "extract"]

Customer Support Agent

[agent]
name = "support"
goal = "Help customers by searching knowledge base and creating tickets"

[agent.capabilities]
web = true
memory = true
api = "ticket-system"
tasks = ["summarize", "categorize"]

Creating an Agent

Initialize Agent

rp agent init my-agent

This creates a template file agents/my-agent.toml.

Configure Agent

Edit the agent file to define:

Goal
Capabilities
Tasks

Push Agent

rp agent push my-agent.toml

Test Agent

rp agent test my-agent --input '{"topic": "AI trends 2025"}'

Deploy Agent

rp agent deploy my-agent

Cost Comparison

Scenario	LLM Calls	Cost	Latency
Traditional (50 operations)	50+	~$0.16	~42s
Agent execution	1	~$0.005	~1s

Agents save 90%+ in both cost and latency.

Best Practices

Define clear goals - Specific goals help agents focus
Limit capabilities - Only give access to what’s needed
Use tasks for complex operations - Break down large prompts into reusable tasks
Test thoroughly - Agents can behave unpredictably
Monitor execution - Review agent logs to optimize prompts

System Prompt

runpiper automatically generates a system prompt for agents based on their configuration. This includes:

Available tools (plan, execute_code, done)
SDK documentation (from capabilities)
Approach guidelines

Next Steps

Tasks: Learn about tasks
Capabilities: Configure external integrations
CLI Reference: Complete CLI command documentation