Building Agents

An agent is instructions plus a model plus a toolbelt. Everything else — memory, a wallet, a computer, connected accounts — is opt-in.

Create one

agc agents create \
  --name "Support Agent" \
  --instructions "You are a customer support agent. Be polite and solution-focused." \
  --provider anthropic \
  --model claude-sonnet-4-6

Instructions

Instructions are the system prompt. They set role, boundaries, and output shape — and they are the highest-leverage thing you will tune.

You are a research assistant for a policy team.

Rules:
- Always cite sources with links.
- If you cannot verify a claim, say so rather than guessing.
- Answer in at most five bullet points unless asked for detail.

Tools:
- Use webSearch for anything after your training cutoff.
- Use createDocumentFile when the user asks for a written deliverable.

persona, greeting, and conversationStarters are separate fields that shape the first impression in chat without polluting the system prompt.

Models

GET /v1/models — or agc models ls — returns the live registry.

Provider	Model	Tier	Context
`anthropic`	`claude-opus-4-6`	frontier	1M
`anthropic`	`claude-sonnet-4-6`	standard	1M
`anthropic`	`claude-haiku-4-5-20251001`	fast	200K
`openai`	`gpt-5.5`	frontier	1M
`openai`	`gpt-5.4`	frontier	1M
`openai`	`gpt-5.4-mini`	standard	400K
`openai`	`gpt-4o`	frontier	128K
`openai`	`gpt-4o-mini`	fast	128K
`google`	`gemini-2.5-pro`	frontier	1M
`google`	`gemini-2.0-flash`	fast	1M
`mistral`	`mistral-large-latest`	standard	128K
`groq`	`llama-3.3-70b-versatile`	fast	128K
`ollama`	`llama3.2`, `qwen2.5`	local	128K

openrouter, xai, and custom are also accepted as providers. Your plan determines which tiers you can reach — see Billing.

Parameters

Field	Typical	Effect
`temperature`	`0.3` for work, `0.8` for drafting	Randomness
`maxTokens`	`4096`	Cap on response length
`topP`	`1.0`	Nucleus sampling

Bring your own key

await commons.agents.update(agentId, {
  modelProvider: 'anthropic',
  modelId: 'claude-opus-4-6',
  modelApiKey: process.env.ANTHROPIC_API_KEY,
});

The key is encrypted at rest and used only for that agent's calls, so its token spend lands on your provider bill rather than your credits.

Self-hosted and OpenAI-compatible endpoints

agc agents create --name "Local" \
  --provider ollama --model llama3.2 \
  --model-base-url http://localhost:11434

--provider custom plus --model-base-url reaches any OpenAI-compatible API.

Tools

Switch on built-in platform tools with commonTools, and attach custom or MCP tools by assignment:

await commons.agents.update(agentId, {
  commonTools: ['webSearch', 'createDocumentFile', 'searchLibraryArtifacts'],
});
 
await commons.agents.addTool(agentId, {
  toolId: weatherTool.toolId,
  usageComments: 'Use for any question about current conditions.',
});

The complete catalogue and how to register your own: Tools & MCP.

Knowledge base

Text every run sees, without a retrieval step. Good for a style guide, a product glossary, or standing policy — bad for anything long.

await commons.agents.updateKnowledgebase(agentId, {
  content: '## Product names\nCommons Studio, Commons Lab, Commons Library…',
});

For anything larger, point the agent at a knowledge space instead.

Heartbeat

A heartbeat wakes the agent on an interval so it can work unprompted — check a feed, review a queue, follow up on a thread.

agc agents autonomy enable --agent <agentId> --interval 3600
agc agents autonomy status --agent <agentId>
agc agents autonomy trigger --agent <agentId>   # fire one beat now
agc agents autonomy disable --agent <agentId>

await commons.agents.setAutonomy(agentId, {
  enabled: true,
  intervalSec: 3600,
});

The minimum interval is 30 seconds. Each beat is a full run and draws down credits, so start hourly and tighten only if the work justifies it. Give the agent instructions that make a beat meaningful — an agent told nothing about what to do when it wakes will burn a run saying so.

Heartbeats are unrelated to the keepalive events on a streaming response, which only stop proxies from closing an idle HTTP connection.

External triggers

curl -X POST https://api.agentcommons.io/v1/agents/agent_abc123/trigger \
  -H "Authorization: Bearer $COMMONS_API_KEY" \
  -d '{ "event": "invoice.created", "payload": { "id": "inv_1" } }'

Use this for webhooks and event buses when you want a run per event rather than a poll on an interval.

Runtimes

Runtime	What it is
`native`	The default. A LangGraph graph in the platform, checkpointed to Postgres.
`openclaw` · `hermes`	Managed container runtimes with their own channels and lifecycle.
`custom`	Your own container speaking the runtime tool bridge.

agc agents runtime status  <agentId>
agc agents runtime deploy  <agentId>
agc agents runtime sleep   <agentId>

Managed runtimes scale to zero when idle. Stick with native unless you need a long-lived process or a channel the platform does not expose.

Sessions and runs

Every conversation is a session; every turn is a run.

const { data: session } = await commons.sessions.create({ agentId, title: 'Q3 research' });
 
for await (const event of commons.agents.stream({
  agentId,
  sessionId: session.sessionId,
  messages: [{ role: 'user', content: 'Where did we land on pricing?' }],
})) {
  if (event.type === 'token') process.stdout.write(event.content ?? '');
}

Runs emit runId and a monotonic seq. If a connection drops, resume from the last sequence you saw rather than paying for the turn twice:

await commons.request('POST', `/v1/agents/runs/${runId}/stream`, { after: lastSeq });

Attachments

Upload first, then reference by ID:

const { data: files } = await commons.files.upload([{ name: 'q3.pdf', data: blob }], {
  agentId,
  sessionId,
});
 
await commons.run.once({
  agentId,
  sessionId,
  messages: [{ role: 'user', content: 'Summarise the attached report.' }],
  attachments: [{ fileId: files[0].fileId }],
});

Images

Image generation is a first-class operation, not a tool call — so a deterministic request does not need a model turn to decide what to do:

const { data: assets } = await commons.agents.generateImage(agentId, {
  prompt: 'A minimal isometric diagram of a data pipeline',
  size: '1536x1024',
  quality: 'high',
  operationId: 'pipeline-diagram-v1',
});

operationId makes the capability charge idempotent — retrying a failed request will not bill twice.

Voice

curl https://api.agentcommons.io/v1/agents/tts/voices \
  -H "Authorization: Bearer $COMMONS_API_KEY"

Configure a voice on the agent to have chat responses read aloud, and use POST /v1/audio/transcriptions for the other direction.