Capabilities

Capabilities are configured connections to external systems that your agents can interact with. They provide secure access to APIs, databases, and other services.

What is a Capability?

A capability defines:

• Connection details - API endpoints, database URLs, authentication
• Available operations - What actions can be performed
• Configuration - Objects, tables, or API routes

Capabilities allow agents to:

• Query databases
• Call external APIs
• Access third-party services
• Perform data operations

Built-in Capabilities

runpiper includes built-in capabilities that require no configuration:

Web

Web search and HTTP fetch capabilities:

// In agent code
const results = web.search("AI news today");
const page = web.fetch(results[0].url);

Function	Description	Cost
web.search(query)	Search the web	$0.001
web.fetch(url)	Fetch a webpage	$0.0002

Memory

Vector search and key-value storage:

// In agent code
memory.add("Important fact", { category: "facts" });
const results = memory.search("important facts");
const value = memory.get("key");
memory.set("key", "value");

Function	Description	Cost
memory.search(query)	Vector similarity search	$0.0005
memory.add(content, metadata)	Store for recall	$0.0003
memory.get(key)	KV retrieval	-
memory.set(key, value)	KV storage	-

Configured Capabilities

HTTP Capability

Connect to any HTTP API:

# capabilities/acme-api.toml
[capability]
name = "acme-api"
type = "http"
base_url = "https://api.acme.com"
auth = "Bearer {{env.ACME_KEY}}"
docs = """
  GET /users - List users
  POST /orders - Create order
"""

Usage in agents:

// In agent code
const users = http.acme.get("/users");
const order = http.acme.post("/orders", {
    user_id: "123",
    items: ["item1", "item2"],
});

Database Capability

Connect to databases for querying:

# capabilities/database.toml
[capability]
name = "my-database"
type = "postgresql"
connection_string = "{{env.DATABASE_URL}}"

Usage in agents:

// In agent code
const results = db.query("SELECT * FROM users WHERE active = $1", [true]);
db.execute("INSERT INTO logs (message) VALUES ($1)", ["Task completed"]);

Function	Description	Cost
db.query(sql, params)	Execute SELECT query	$0.0001
db.execute(sql, params)	Execute INSERT/UPDATE/DELETE	$0.0001

Salesforce

Connect to Salesforce CRM:

# capabilities/salesforce.toml
[capability]
name = "salesforce"
type = "salesforce"
instance = "acme.salesforce.com"
objects = ["Account", "Contact", "Opportunity"]

Usage in agents:

// In agent code
const accounts = salesforce.query("SELECT Name, Industry FROM Account");
const contact = salesforce.create("Contact", {
    FirstName: "John",
    LastName: "Doe",
    Email: "john@example.com",
});

Capability Configuration

Type

The type of service:

• http - REST API
• postgresql - PostgreSQL database
• mysql - MySQL database
• salesforce - Salesforce CRM

Authentication

Use environment variables for credentials:

[capability]
name = "api"
type = "http"
base_url = "https://api.example.com"
auth = "Bearer {{env.API_KEY}}"

Set environment variables:

• In .env file locally
• In your runpiper organization settings (cloud)

Documentation

Include API documentation to help the LLM understand available operations:

docs = """
  GET /users - Get all users (paginated)
  GET /users/:id - Get user by ID
  POST /users - Create new user
    Body: { name, email, role }
"""

Capabilities Directory Structure

capabilities/
├── web (built-in)
├── memory (built-in)
├── acme-api.toml
├── database.toml
└── salesforce.toml

Environment Variables

Use {{env.VAR_NAME}} to reference environment variables in capability configs:

[capability]
name = "database"
type = "postgresql"
connection_string = "{{env.DATABASE_URL}}"

When pushing tasks or agents, these variables will be resolved from:

• Local .env file (CLI)
• Organization environment variables (Cloud)

Security Best Practices

1. Never commit secrets - Use environment variables only
2. Least privilege - Grant minimal required permissions
3. Separate environments - Use different credentials for dev/prod
4. Rotate credentials - Regularly update API keys
5. Audit access - Review which agents use which capabilities

Cost Summary

Operation	Cost
web.search	$0.001
web.fetch	$0.0002
db.query	$0.0001
db.execute	$0.0001
memory.search	$0.0005
memory.add	$0.0003
Custom HTTP	$0.0001 per call
Database	Per query/execute

Next Steps

• Tasks: Learn about tasks
• Agents: Build agents that use capabilities
• Self-Hosted Deployment: Run your own instance