Define an Agent

Create agents with defineAgent() — configuration, tools, LLM, system prompt, and advanced options.

Basic Usage

import { defineAgent, defineTool, createLLM } from '@ahzan-agentforge/core';
import { z } from 'zod';

const agent = defineAgent({
  name: 'my-agent',
  description: 'Does useful things',
  tools: [myTool],
  llm: createLLM({ provider: 'anthropic', model: 'claude-sonnet-4-20250514' }),
  systemPrompt: 'You are a helpful assistant.',
});

from agentforge import define_agent, create_llm

agent = define_agent(
    name="my-agent",
    description="Does useful things",
    tools=[my_tool],
    llm=create_llm(provider="anthropic", model="claude-sonnet-4-20250514"),
    system_prompt="You are a helpful assistant.",
)

AgentConfig

Full configuration options:

interface AgentConfig {
  // Required
  name: string;                    // Unique agent name
  description: string;             // What the agent does (sent to LLM)
  tools: Tool[];                   // Available tools
  llm: LLM;                       // LLM instance from createLLM()
  systemPrompt: string;            // System prompt for the LLM

  // Execution
  maxSteps?: number;               // Max loop iterations (default: 20)
  stateStore?: StateStore;         // State persistence (default: in-memory)
  rollbackOnFailure?: boolean;     // Auto-rollback on failure

  // Runtime features
  hooks?: AgentHooks;              // Lifecycle callbacks
  memory?: AgentMemoryConfig;      // Memory configuration
  budget?: BudgetConfig;           // Token/cost limits
  policy?: PolicyConfig;           // Autonomy rules
  model?: string;                  // Override LLM model
  anomalyDetection?: AnomalyConfig; // Anomaly detection
}

Agent Methods

The Agent class returned by defineAgent() provides:

Method	Returns	Description
`run(input)`	`Promise<RunResult>`	Execute the agent
`stream(input)`	`AsyncGenerator<AgentStreamEvent>`	Stream execution events
`approve(runId, approved)`	`Promise<RunResult>`	Approve/deny a paused run
`remember(content, metadata, context?)`	`Promise<void>`	Store a memory
`recall(query, context?, options?)`	`Promise<MemorySearchResult[]>`	Search memories
`getName()`	`string`	Get agent name
`getConfig()`	`Readonly<AgentConfig>`	Get frozen config

With Budget

const agent = defineAgent({
  name: 'budgeted-agent',
  description: 'Cost-controlled agent',
  tools: [myTool],
  llm,
  systemPrompt: '...',
  budget: {
    maxCostUsd: 0.50,
    maxTokens: 50_000,
    warnThreshold: 0.8,
  },
});

With Autonomy Policy

const agent = defineAgent({
  name: 'governed-agent',
  description: 'Agent with tool restrictions',
  tools: [readTool, writeTool, deleteTool],
  llm,
  systemPrompt: '...',
  policy: {
    defaultPermission: 'allow',
    tools: [
      { pattern: 'delete*', permission: 'escalate', reason: 'Destructive action' },
      { pattern: 'admin_*', permission: 'deny' },
    ],
  },
});

With Memory

import { InMemoryMemoryStore } from '@ahzan-agentforge/core';

const agent = defineAgent({
  name: 'remembering-agent',
  description: 'Agent with memory',
  tools: [myTool],
  llm,
  systemPrompt: '...',
  memory: {
    store: new InMemoryMemoryStore(),
    config: {
      autoCapture: true,
      retrieveBeforeStep: true,
      maxRetrieved: 5,
    },
  },
});

With State Persistence

import { RedisStateStore } from '@ahzan-agentforge/core';

const agent = defineAgent({
  name: 'persistent-agent',
  description: 'Survives crashes',
  tools: [myTool],
  llm,
  systemPrompt: '...',
  stateStore: new RedisStateStore({ url: 'redis://localhost:6379' }),
});

Next Steps

Running Agents — execute and get results
Streaming — real-time event streams
Hooks — lifecycle callbacks

On this page