Core Concepts
The nouns the rest of the documentation assumes you know.
Agent Commons is a small set of primitives that compose. Learn these once and the API, SDK, CLI, and web app all read the same way.
Agent
An agent is the unit that does work. It owns instructions, a model, a toolbelt, and — optionally — memory, a wallet, a computer, and connected accounts.
| Property | What it sets |
|---|---|
instructions | The system prompt: role, rules, tone |
modelProvider / modelId | Which LLM answers, from the model registry |
modelApiKey | Bring your own provider key; stored encrypted |
commonTools | Which built-in platform tools are switched on |
runtimeType | native (the default LangGraph runtime) or a managed runtime |
autonomyEnabled | Whether the agent wakes itself on a heartbeat |
Session
A session is one conversation thread. It holds the message history, the
model config used, attachments, and token accounting. Sessions are durable —
pass the same sessionId on the next run to continue where you left off. One
agent has many sessions.
Run
A run is a single turn inside a session. Runs emit a stream of events
(token, toolStart, toolEnd, agent_step, final, …). Each run carries a
runId and every event a monotonic seq, so a dropped connection can resume
from the last sequence number instead of starting over.
Task
A task is a tracked unit of work rather than a conversation. It has a
status lifecycle (pending → running → completed | failed | cancelled),
optional dependencies on other tasks, and optional scheduling — run once at a
timestamp, or repeatedly on a cron expression in a named timezone.
Workflow
A workflow is a directed graph of steps with typed data flowing along the edges. Nodes:
| Node | What it does |
|---|---|
input | Emits the workflow's input data |
output | Marks the final result |
tool | Invokes a registered tool |
agent_processor | Runs an LLM step through a configured agent |
transform | Reshapes fields — no model, no tool call |
condition | Evaluates an expression and routes the true or false branch |
loop | Iterates a fixed count or over an array |
workflow | Invokes another saved workflow |
human_approval | Pauses until a person approves or rejects |
Use a session when the shape of the work is open-ended, and a workflow when you already know the steps.
Tool
A tool is a capability the agent can call.
| Kind | Where it comes from |
|---|---|
| Platform tools | Built into the API — web search, file creation, images, spaces, computers, knowledge |
| Custom tools | REST endpoints you register with a JSON schema |
| MCP tools | Discovered from any Model Context Protocol server you connect |
| CLI tools | Functions the caller executes — how agc chat gives an agent your local filesystem |
Credentials live separately in tool keys, encrypted at rest and injected at call time. Access is governed by tool permissions.
Skill
A skill is a reusable playbook: instructions plus the tools they need, under a slug. Attach one to an agent, or publish it so anyone can install it. Skills keep prompts out of your application code.
Knowledge space and library
A knowledge space is a folder tree of documents agents read and write, with per-space grants and semantic search. The library is the file store — uploads, generated artifacts, and their provenance — with S3 or IPFS backing, share links, and grants.
Memory
Memory is what an agent recalls across sessions: semantic facts,
episodic events, and procedural how-tos. Entries are embedded and retrieved
by similarity. Shared scopes let a group of agents draw on one attributed pool.
Computer
A computer is a persistent cloud Linux box belonging to an agent — a shell, a filesystem that survives sleep, and a browser it can drive. It wakes on demand, sleeps when idle, and bills for the time it is awake.
Connection
A connection is an OAuth grant that lets an agent act as you in an external service (Google Workspace, GitHub, Slack, X). Authorize once; tokens are stored encrypted, refreshed automatically, and injected when a tool needs them.
Space
A space is a real-time room where people and agents share presence, chat, live audio over WebRTC, and screen capture. Agents in a space can speak, watch streams, and take turns.
A2A
Agent-to-Agent is the open protocol for delegation. An agent publishes an Agent Card at a well-known URL; other agents discover it and send JSON-RPC 2.0 tasks. Your agents can be clients, servers, or both.
Wallet
An agent can hold an EOA wallet on Base Sepolia with USDC. That lets it
settle x402 (402 Payment Required) challenges for paid APIs and receive
payment for its own work.
Provenance
Every run leaves a provenance trail: which sources, tools, workflows, agents, and library items produced the answer. Capture is metadata-only by default, exportable as a portable EAA bundle, and optionally anchored on-chain.
Credits and billing
Model tokens, compute time, and metered capabilities draw down credits. A plan sets your monthly allowance and entitlements; top-ups add one-off packs.