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.

Every time an agent fires — whether from a trigger or a manual invocation — it writes a run row. The run captures status, tool calls, token usage, duration, and a tool-resolution trace that explains why the agent saw the tools it saw. Runs are how you answer “did it work?” and “why didn’t it work?”

​
What you can do

  • List recent runs for an agent.
  • Follow runs live as they fire (tail mode).
  • Inspect a specific run’s full trace.
  • Test-fire an agent synchronously with a synthetic event payload.
“Show me the last 20 runs for the support agent.” “Why didn’t run run_abc123 use any tools?” “Test the triage agent with this fake event: { "title": "broken checkout" }.”
The Concierge reads the run row plus the tool-resolution trace and explains the result in plain English.

​
Via the CLI

# List recent runs
copass agent runs support
copass agent runs support --limit 50

# Follow live
copass agent runs support --follow

# Test-fire with a synthetic event
copass agent test support --event-payload '{"title":"broken checkout"}'

​
Via the SDK / API

const runs = await client.agents.runs.list(sandboxId, 'support', { limit: 20 });
const trace = await client.agents.runs.getTrace(sandboxId, 'support', runId);

// Synchronous test fire
const { run_id, status, output_text } = await client.agents.test(sandboxId, 'support', {
  event_payload: { title: 'broken checkout' },
});

​
What a run row contains

FieldPurpose
run_idStable id; the audit anchor.
statussucceeded / failed / cancelled.
trigger_idWhich trigger fired this run (null for manual / test runs).
tokens_in, tokens_outPer-run usage.
duration_msEnd-to-end.
error_messageOn failures.
tool_resolution_traceThe full audit of which sources resolved, which tools the model saw, which allowlist entries were filtered out. The drift detector.

​
Reading the tool-resolution trace

The trace is what makes “agent silently did nothing” debuggable. Key fields:
FieldWhat it tells you
sources_resolvedWhich tool sources actually built. If pipedream is missing, no integration tools showed up.
sources_skippedSources whose builders soft-failed (most common: missing OAuth).
tool_names_advertisedThe exact strings the model saw. If your expected tool isn’t here, the model couldn’t have called it.
allowlist_filtered_outTools removed because they weren’t in tool_allowlist.
allowlist_missing_entriesAllowlist entries that didn’t match any real tool — the stale-allowlist drift signal. Fix these immediately.
duration_msHow long resolution took.

​
One-shot runs from the terminal — copass run

For ad-hoc invocations without setting up a trigger, copass run fires an agent turn from the shell using your connected integrations as tools: 
# Default agent in the active sandbox
copass run "draft a release note for the last 5 GitHub commits"

# Pick a specific agent
copass run --agent triage "what's blocked across my open Linear tickets?"

# Pipe input
git log --oneline -20 | copass run "summarize these commits"
The output streams back to your terminal. Behind the scenes it goes through the same Agent Router endpoint as triggered runs — same event stream, same tool catalog, same billing.

​
Test before binding

Always test-fire a fresh agent before pointing live triggers at it. The CLI version: 
copass agent test support --event-payload '{"title":"sample"}'
Returns the run_id synchronously. Pull the trace via runs --follow or ask the Concierge to summarize.

​
Common patterns

Test → trigger → tail

Test-fire while iterating on the prompt; once it’s working, attach a trigger and use runs --follow to watch real fires.

Debug silent no-ops

“My agent fires but doesn’t do anything” almost always means a tool-resolution issue. Pull the trace; check allowlist_missing_entries and sources_skipped.

Audit by trigger

Filter run history by trigger_id to see only the runs from a specific binding — useful when one agent has multiple triggers.

Cost-watch by token usage

Aggregate tokens_in + tokens_out across runs in a window to catch a runaway agent before it dents your billing.

​
Next steps

  • Build an agent — start here.
  • Triggers — what causes runs to fire.
  • Tools — diagnose tool-resolution traces.
  • Events — the event types streaming during a run.