Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.copass.com/llms.txt

Use this file to discover all available pages before exploring further.

An agent in Copass is a stored configuration: identity, system prompt, tool surface, model settings. You create one, point triggers at it (or invoke it directly), and it runs against the integrations and data in its sandbox. Every sandbox can hold many agents. They’re cheap — spin up specialists rather than overloading one big one.

​
What you can do

  • Create an agent with a slug, name, system prompt, and model settings.
  • List, show, update, or archive existing agents.
  • Test-fire an agent synchronously with a fake event payload.
  • Inspect the dynamic tool catalog the agent will see at runtime.
“Create an agent named support that answers Slack questions using our knowledge graph.” “Switch the support agent to Sonnet and raise the turn limit to 15.” “Show me all my agents.” “Test the triage agent with this fake event: { "title": "broken checkout" }.”
The Concierge handles slug picking, default model selection, tool-source defaults, and the right pre-flights before any change.

​
Via the CLI

The Ink-rendered agent setup wizard walks you through creation interactively: 
copass agent setup            # interactive wizard (recommended for first agent)
Or scripted: 
# Create with a one-line prompt
copass agent create support \
  --name "Support agent" \
  --prompt "You are a helpful support agent..." \
  --model claude-sonnet-4-6

# Or pass a prompt file
copass agent create triage --prompt-file ./prompts/triage.md

# CRUD
copass agent list
copass agent show support
copass agent update support --temperature 0.4 --max-turns 15
copass agent archive support              # soft, reversible

​
Via the SDK / API

// Create
const agent = await client.agents.create(sandboxId, {
  slug: 'support',
  name: 'Support agent',
  system_prompt: 'You are a helpful support agent...',
  model_settings: { backend: 'anthropic', model: 'claude-opus-4-7', temperature: 0.4 },
});

// List / show
const agents = await client.agents.list(sandboxId);
const detail = await client.agents.get(sandboxId, 'support');

// Patch (partial update — supplied fields override; others preserved)
await client.agents.update(sandboxId, 'support', {
  model_settings: { temperature: 0.4, max_turns: 15 },
});

// Archive (reversible)
await client.agents.archive(sandboxId, 'support');

​
Anatomy of an agent row

FieldPurpose
slugStable wire identifier (lowercase, [a-z0-9-]+). What CLI commands and triggers reference.
name, descriptionHuman-readable.
system_promptThe behavioral spec. Updates bump version.
tool_sourcesWhich tool resolvers compose for this agent (copass_retrieval, pipedream, user_mcp, …). Default depends on sandbox.
tool_allowlistWhich tool names are callable from those sources. [] means “all allowed.”
model_settingsbackend (anthropic / google), model, temperature, max_tokens, max_turns, timeout_s.
version, statusServer-managed. status: archived stops triggers from firing.

​
Common patterns

Specialist > generalist

One agent per job (triage, support, weekly-summary) with tight prompts beats a single overloaded agent. Switching models per-job is cheap.

Test before you wire

Use agent test (or “test the agent with this fake event”) before pointing triggers at it. See Runs.

Tighten allowlist after creation

Default to tool_allowlist: [] (everything) while iterating. Lock down to specific tool names once the agent is stable. See Tools.

Archive, don't delete

archive flips status without losing config or run history. Reversible. The CLI has destroy for permanent removal.

​
Next steps

  • Triggers — wire an agent to fire on data-source events.
  • Tools — what tools the agent will see and how they’re composed.
  • Runs — list, follow, and test runs.
  • Agent Router overview — the runtime layer agents execute on.