StatefulAxAgent Class

API reference for the StatefulAxAgent class

The StatefulAxAgent class represents an individual agent in an AxCrew. This class extends the base AxAgent class from AxLLM and adds state management capabilities.

Constructor

constructor(
  agentConfig: AgentConfig, 
  state: StateInstance, 
  dependentAgents?: Map<string, StatefulAxAgent>
)

Creates a new StatefulAxAgent instance.

You typically don't create instances of this class directly. They are created by the AxCrew class when you call addAgent, addAgentsToCrew, or addAllAgents.

Properties

state

state: StateInstance

The shared state instance that can be accessed by this agent.

agent.state.set('result', 42);
const result = agent.state.get('result');

name

name: string

The name of the agent as defined in the configuration.

console.log(`Agent name: ${agent.name}`);

config

config: AgentConfig

The complete configuration for this agent.

console.log(`Agent model: ${agent.config.ai.model}`);

Methods

forward

async forward(
  input: Record<string, any>, 
  options?: { onStream?: (chunk: string) => void }
): Promise<Record<string, any>>

Executes the agent with the provided input.

Parameters:

input - The input to the agent (should match the input signature)
options - Optional execution options
- onStream - A callback function for streaming responses

Returns: The agent's response (matches the output signature)

// Basic usage
const response = await agent.forward({ task: "Create a plan" });
console.log(response.plan);
 
// With streaming
await agent.forward(
  { task: "Create a detailed plan" },
  {
    onStream: (chunk) => {
      process.stdout.write(chunk);
    }
  }
);

streamingForward

streamingForward(
  input: Record<string, any>
): AsyncGenerator<StreamChunk>

Executes the agent with streaming, returning an async generator.

const gen = agent.streamingForward({ task: "Create a plan" });
 
for await (const chunk of gen) {
  if (chunk.delta) {
    console.log(chunk.delta);
  }
}

getLastUsageCost

getLastUsageCost(): UsageCost | undefined

Gets the cost information for the most recent call to the agent.

const lastCost = agent.getLastUsageCost();
if (lastCost) {
  console.log(`Last call cost: $${lastCost.totalCost}`);
  console.log(`Tokens used: ${lastCost.tokenMetrics.totalTokens}`);
}

getAccumulatedCosts

getAccumulatedCosts(): UsageCost | undefined

Gets the accumulated cost information for all calls to the agent.

const costs = agent.getAccumulatedCosts();
if (costs) {
  console.log(`Total accumulated cost: $${costs.totalCost}`);
}

getMetrics

getMetrics(): MetricsSnapshot | undefined

Gets the metrics snapshot for this agent.

const metrics = agent.getMetrics?.();
console.log(metrics);

resetCosts

resetCosts(): void

Resets the cost tracking for this agent.

agent.resetCosts();

getPlaybook

getPlaybook(): Record<string, any> | undefined

Gets the ACE playbook for this agent (if ACE is configured).

const playbook = agent.getPlaybook?.();
if (playbook) {
  console.log("Learned rules:", playbook);
}

Usage in AxCrew

Agents are typically accessed through the AxCrew's agents map:

import { AxCrew } from '@amitdeshmukh/ax-crew';
 
const crew = new AxCrew(config);
await crew.addAllAgents();
 
// Get an agent from the crew
const planner = crew.agents.get('Planner');
 
// Use the agent
const response = await planner.forward({ task: "Create a plan" });
console.log(response.plan);
 
// Check agent costs
const cost = planner.getLastUsageCost();
console.log(`Cost: $${cost.totalCost}`);

Sub-agent Usage

When an agent depends on other agents, it can use them as sub-agents:

// Manager agent depends on Planner and Calculator
const manager = crew.agents.get('Manager');
 
// Get usage costs including sub-agent costs
const managerResponse = await manager.forward({ question: "How long?" });
const totalCost = manager.getAccumulatedCosts();

The getAccumulatedCosts() method includes costs from any sub-agent calls.

StatefulAxAgent Class

On this page