Skip to content
cycgraph

Agents

Agents are simply configurations that describe how to use an LLM to perform a task. There are no base classes to extend, no framework to inherit from. These rules feed into the agent runtime.

Naming: agents are authored in idiomatic camelCase (systemPrompt, maxSteps, permissions.readKeys, …). registry.register accepts these and stores the snake_case wire format; loadAgent returns snake_case. Snake_case input is still tolerated for back-compat.

Configuration

Section titled “Configuration”
Field Type Default Description
id string (UUID) auto Unique identifier
name string required Human-readable name
description string — Used by supervisor nodes to route work to this agent.
model string required Model
provider string required Provider
systemPrompt string required System prompt.
temperature number 0.7 Value between 0.0 (deterministic) and 1.0 (creative).
maxSteps number 10 Safety limit for multi-step tool execution loops.
tools ToolSourceConfig[] [] MCP tools
modelPreference ModelTier — Capability tier ('high', 'medium', 'low') for budget-aware model selection. When set and a resolver is configured, overrides model at runtime.
providerOptions object — Provider-specific options
permissions object required Zero-trust state permissions (readKeys, writeKeys)

Agent registry

Section titled “Agent registry”

The Agent Registry is a lookup interface to load these configurations into the runtime.

Interface

Section titled “Interface”

When implementing a custom registry or interacting with an existing one, the following methods are available:

Method Parameters Return Type Description
register entry: AgentRegistryConfig string | Promise<string> Register a new agent configuration (camelCase) and return its ID.
loadAgent id: string Promise<AgentRegistryEntry | null> Load an agent configuration by its ID (snake_case wire shape).
updateAgent id: string, updates: Partial<AgentRegistryConfig> Promise<void> (Optional) Update an existing agent configuration.
listAgents opts?: { limit?: number; offset?: number } Promise<AgentRegistryEntry[]> (Optional) List registered agents with pagination support.
deleteAgent id: string Promise<boolean> (Optional) Delete an agent by its ID.

Example

Section titled “Example”
import { InMemoryAgentRegistry } from '@cycgraph/orchestrator';


const registry = new InMemoryAgentRegistry();


const researcherId = registry.register({
  name: 'Researcher',
  model: 'claude-sonnet-4-6',
  provider: 'anthropic',
  systemPrompt: 'You are a research specialist...',
  temperature: 0.5,
  maxSteps: 5,
  tools: [{ type: 'mcp', serverId: 'web-search' }],
  permissions: {
    readKeys: ['topic'],
    writeKeys: ['notes']
  },
});

Budget-aware model selection

Section titled “Budget-aware model selection”

Instead of hardcoding a model, agents can declare a capability tier via modelPreference. When a ModelResolver is configured on the GraphRunner, the engine resolves the tier to a concrete model at runtime — automatically downgrading to cheaper models when the workflow budget is running low.

const writerId = registry.register({
  name: 'Writer',
  model: 'claude-sonnet-4-6',
  modelPreference: 'medium',
  provider: 'anthropic',
  systemPrompt: 'You write clear summaries.',
  tools: [],
  permissions: {
    readKeys: ['notes'],
    writeKeys: ['draft']
  },
});

See Budget-Aware Model Selection for the full setup guide.

Next steps

Section titled “Next steps”