Cursor

This guide shows how to configure Cursor to build agentic functions and agents with the Agentica SDK

Prerequisites

Cursor editor installed

Project rules

Create project rules that all team members can use. In your documentation repository root:

mkdir -p .cursor

Create .cursor/rules.md:

# Agentica Documentation

## Overview

Agentica is a library for integrating agentic features and agents into Python applications.

## Basics

The primary method of interaction is through the `@agentic()` decorator, which works like this:

```python
from agentica import agentic

# Defines an agent-backed function
@agentic()
async def add(a: int, b: int) -> int:
	"""Returns the sum of a and b"""
	...

# Calls the agent-backed function
result = await add(1, 2) # This addition is done by an agent via the agentica framework
assert result == 3
```

This allows you to use agents to implement functions which are not possible to implement in pure python. Functions decorated with `@agentic` MUST be `async`.

The alternative syntax is to `spawn` an agent.

```python
from agentica import spawn

# Defines an agent
agent = await spawn(premise="You are a truth-teller.")

# Calls agent
result: bool = await agent.call(bool, "The Earth is flat")
assert result == False

```

The creation and call of agents created with `spawn` are always awaitable. When calling an agent you **must** always pass in the return type as the first argument, followed by an argument of type `str`.

### Return Types

Return types are optional and flexible:

```python
# Return type defaults to str if not specified
result = await agent.call("What is 2+2?")  # Returns str

# Specify exact types for structured output
result: int = await agent.call(int, "What is 2+2?")  # Returns int
result: dict[str, int] = await agent.call(dict[str, int], "Count items by category")

# Use None for side-effects only
await agent.call(None, "Send a message to John")  # No return value needed
```

## Agent Instantiation

There are two ways to create agents:

### Using `spawn` (async)
Use `spawn` for most cases - it's awaitable and async-friendly:

```python
agent = await spawn(premise="You are a helpful assistant.")
```

### Using `Agent()` directly (sync)
Use direct instantiation when you need synchronous creation, such as in `__init__` methods:

```python
from agentica import Agent

class CustomAgent:
    def __init__(self, directory: str):
        # Must be synchronous - use Agent() not spawn()
        self._brain = Agent(
            premise="You are a specialized assistant.",
            scope={"tool": some_tool}
        )

    async def run(self, task: str) -> str:
        return await self._brain.call(str, task)
```

**Tip**: Direct `Agent` instantiation is particularly useful when building custom agent classes or in contexts that cannot be async.

## Premise vs System Prompt

You can control the agent's instructions in two ways:

```python
# Use 'premise' to add context to the default system prompt
agent = await spawn(premise="You are a math expert.")

# Use 'system' for full control of the system prompt
agent = await spawn(system="You are a helpful assistant. Always respond with JSON.")
```

**Note**: You cannot use both `premise` and `system` together.

## Passing in objects

If you want agentic function or agent to use a function, class, object etc. inside an agentic function, simply put it in the `@agentic` decorator or `scope` in the call to `spawn`.

```python
from agentica import agentic, spawn

# User-defined function
from tools import web_search

# Defines agent
agent = await spawn(premise="You are a truth-teller.", scope={"web_search" : web_search})

# Defines the agent-backed function
@agentic(scope={'web_search': web_search})
async def truth_teller(statement: str) -> bool:
  """Returns whether or not a statement is True or False."""
  ...
```

### SDK Integration Pattern

Extract specific methods from SDK clients for focused scope:

```python
from slack_sdk import WebClient

# Extract only the methods you need
slack_conn = WebClient(token=SLACK_BOT_TOKEN)
list_users = slack_conn.users_list
send_message = slack_conn.chat_postMessage

@agentic(scope={'list_users': list_users, 'send_message': send_message}, model="openai/gpt-5")
async def send_team_update(message: str) -> None:
    """Send a message to all team members."""
    ...
```

### Per-Call Scope

You can also add scope per invocation:

```python
agent = await spawn(premise="Data analyzer")

# Add resources for this specific call
result = await agent.call(
    dict[str, int],
    "Analyze the dataset",
    dataset=pd.read_csv("data.csv"),
    analyzer_tool=custom_analyzer
)
```

## Model Selection

Agentica supports any text-to-text model provided on OpenRouter. Specify with the `model` parameter:

```python
# For agents
agent = await spawn(
    premise="Fast responses needed",
    model="openai/gpt-5"  # Default is 'openai/gpt-4.1'
)

# For agentic functions
@agentic(model="anthropic/claude-sonnet-4.5")
async def analyze(text: str) -> dict:
    """Analyze the text."""
    ...
```

**Supported models**:
Any OpenRouter model slug (e.g. `google/gemini-2.5-flash`).

## Token Limits

Control the maximum number of tokens generated with `max_tokens`:

```python
from agentica import spawn, agentic, MaxTokens

# For agents
agent = await spawn(
    premise="Brief responses only",
    max_tokens=500  # Limit total output tokens per invocation
)

# For agentic functions
@agentic(max_tokens=1000)
async def summarize(text: str) -> str:
    """Create a concise summary."""
    ...

# For finer control, use MaxTokens:
# - per_invocation: total tokens across all rounds
# - per_round: tokens per inference round
# - rounds: maximum number of inference rounds
agent = await spawn(
    premise="Brief responses only",
    max_tokens=MaxTokens(per_invocation=5000, per_round=1000, rounds=5)
)
```

**Use cases**:
- Ensure brief responses for cost control
- Prevent overly long outputs
- Match specific output length requirements

If the response would exceed `max_tokens`, a `MaxTokensError` will be raised. See [Error Handling](#error-handling) for how to handle this.

## Tracking Token Usage

Track token consumption with `last_usage` and `total_usage`. These return `ResponseUsage` from `openai.types.responses`, which includes detailed breakdowns for cached and reasoning tokens:

```python
from agentica import spawn, agentic, last_usage, total_usage

# Agents have methods
agent = await spawn(premise="You are helpful.")
await agent.call(str, "Hello!")
await agent.call(str, "How are you?")

u = agent.last_usage()  # ResponseUsage from last invocation
print(f"Input tokens:     {u.input_tokens}")
print(f"Output tokens:    {u.output_tokens}")
print(f"Cached tokens:    {u.input_tokens_details.cached_tokens}")
print(f"Reasoning tokens: {u.output_tokens_details.reasoning_tokens}")

u = agent.total_usage()  # Cumulative ResponseUsage across all invocations

# Agentic functions use standalone functions
@agentic()
async def analyze(text: str) -> str:
    """Analyze the text."""
    ...

await analyze("Some text")
print(last_usage(analyze))   # ResponseUsage(input_tokens=..., output_tokens=..., ...)
print(total_usage(analyze))  # Cumulative usage
```

The `ResponseUsage` object contains:
- `input_tokens`: tokens consumed as input
- `output_tokens`: tokens generated as output
- `input_tokens_details.cached_tokens`: tokens served from cache
- `output_tokens_details.reasoning_tokens`: tokens used for reasoning

## Persistence

Agentic functions can maintain state between calls:

```python
# Stateful agentic function
@agentic(persist=True, model="openai/gpt-4.1")
async def chatbot(message: str) -> str:
    """A chatbot that remembers conversation history."""
    ...

# First call
response1 = await chatbot("My name is Alice")

# Second call - remembers previous context
response2 = await chatbot("What's my name?")  # Will know it's Alice
```

**Tip**: Use `persist=True` when you need conversation history or stateful behavior in agentic functions. For agents, state is maintained automatically across calls to the same agent instance.

## Streaming

Streaming is supported for both agents and agentic function, most straightforwardly by using a `StreamLogger`.

```python
from agentica import spawn
from agentica.logging.loggers import StreamLogger

agent = await spawn(premise="You are a truth-teller.")

stream = StreamLogger()
with stream:
    result = asyncio.create_task(
        agent.call(bool, "Is Paris the capital of France?")
    )
```

This creates an async generator `stream` containing producing the streamed in text-chunks of the invocation within the with-statement.
The stream can be consumed like this:

```python
# Consume stream FIRST for live output
async for chunk in stream:
    print(chunk.content, end="", flush=True)

# Then await result
final_result = await result
```

Each `Chunk` object contains:
- `content`: the text content of the chunk
- `role`: one of `'user'`, `'agent'`, or `'system'`
- `type`: optional — one of `'reasoning'`, `'output_text'`, `'code'`, `'usage'`, `'invocation_exit'`, or `None`

`StreamLogger` also accepts an `on_chunk` callback and `include_usage` flag:

```python
# Forward chunks in real time over a WebSocket
async def forward(chunk: Chunk):
    await websocket.send(chunk.content)

stream = StreamLogger(on_chunk=forward, include_usage=True)
```

By default, usage chunks (`chunk.type == 'usage'`) are filtered out. Set `include_usage=True` to receive them.

**Important**: The stream should be consumed **before** awaiting the result, otherwise you won't see the live text generation.

## Logging and Debugging

Agentica provides built-in logging to help debug agents and agentic functions.

### Default Logging

By default, all agents and agentic functions use `StandardListener` which:
- Prints lifecycle events to stdout with colors
- Writes chat histories to `./logs/agent-<id>.log`

```shell
Spawned Agent 25 (./logs/agent-25.log)
► Agent 25: Calculate the 32nd power of 3
◄ Agent 25: 1853020188851841
```

### Contextual Logging

Temporarily change logging for specific code sections:

```python
from agentica.logging.loggers import FileLogger, PrintLogger

# Only log to file in this block
with FileLogger():
    agent = await spawn(premise="Debug this agent")
    await agent.call(int, "Calculate something")

# Multiple loggers can be nested
with PrintLogger():
    with FileLogger():
        # Both print AND file logging active
        agent = await spawn(premise="Dual logging")
        await agent.call(str, "Hello")
```

### Disable Logging

```python
from agentica.logging.agent_logger import NoLogging

with NoLogging():
    agent = await spawn(premise="Silent agent")
    await agent.call(int, "Secret calculation")
```

### Per-Agent/Function Logging

```python
from agentica.logging import PrintOnlyListener, FileOnlyListener

# Attach listener to specific agent
agent = await spawn(
    premise="Custom logging",
    listener=PrintOnlyListener  # Only print, no files
)

# Attach listener to specific agentic function
@agentic(listener=FileOnlyListener)
async def my_func(a: int) -> str:
    """Only logs to file."""
    ...
```

### Global Logging Configuration

```python
from agentica.logging import set_default_agent_listener, PrintOnlyListener

# Change default for all agents/functions
set_default_agent_listener(PrintOnlyListener)

# Disable all logging by default
set_default_agent_listener(None)
```

**Logging Priority** (highest to lowest):
1. Contextual loggers (via `with` statement)
2. Per-agent/function listener
3. Default listener

## Using MCP

If you want the agentic function or agent to use an MCP server, simply put it in the `@agentic` decorator or the call to `spawn`.

```python
from agentica import agentic, spawn

# Defines the agent
agent = await spawn(premise="You are a truth-teller.", mcp="path/to/config.json")

# Defines the agent-backed function
@agentic(mcp="path/to/config.json")
async def truth_teller(statement: str) -> bool:
  """Returns whether or not a statement is True or False."""
  ...
```

where "path/to/config.json" is a standard JSON config file such as:

```json
{
  "mcpServers": {
    "tavily-remote-mcp": {
      "command": "npx -y mcp-remote https://mcp.tavily.com/mcp/?tavilyApiKey=<your-api-key>",
      "env": {}
    }
  }
}
```

## Error Handling

Agentica provides comprehensive error handling through the `agentica.errors` module.

### SDK Errors

All Agentica errors inherit from `AgenticaError`, making it easy to catch all SDK-related errors:

```python
from agentica import agentic
from agentica.errors import AgenticaError, RateLimitError, InferenceError

@agentic()
async def process_data(data: str) -> dict:
    """Process the data."""
    ...

try:
    result = await process_data(raw_data)
except RateLimitError as e:
    # Handle rate limiting
    await asyncio.sleep(60)
    result = await process_data(raw_data)
except InferenceError as e:
    # Handle all inference service errors
    logger.error(f"Inference failed: {e}")
    result = {}
except AgenticaError as e:
    # Catch any other SDK errors
    logger.error(f"Agentica error: {e}")
    raise
```

**Error hierarchy:**
- `AgenticaError` - Base for all SDK errors
  - `ServerError` - Base for remote operation errors
    - `GenerationError` - Base for agent generation errors
      - `InferenceError` - HTTP errors from inference service
      - `MaxTokensError`, `ContentFilteringError`, etc.
  - `ConnectionError` - WebSocket and connection errors
  - `InvocationError` - Agent invocation errors

### Custom Exceptions

You can define custom exceptions and pass them into the `@agentic()` decorator so the agent can raise them:

```python
class DataValidationError(Exception):
    """Raised when input data fails validation."""
    pass

@agentic(DataValidationError)
async def analyze_data(data: str) -> dict:
    """
    Analyze the dataset.

    Raises:
        DataValidationError: If data is empty or malformed
        ValueError: If data format is not supported

    Returns a dictionary with analysis results.
    """
    ...

try:
    result = await analyze_data(raw_data)
except DataValidationError as e:
    logger.warning(f"Invalid data: {e}")
    result = {"status": "validation_failed"}
```

**Tip**: The agent can see your docstrings! Document exception conditions clearly in the `Raises:` section, and the agent will raise them appropriately.

## Common Patterns

### Stateful Data Analysis

Agents maintain context across calls and can manipulate variables by reference:

```python
from agentica import spawn
import pandas as pd

agent = await spawn()

# First analysis
result = await agent.call(
    dict[str, int],
    "Count movies by genre",
    dataset=pd.read_csv("movies.csv")
)

# Agent remembers previous result
filtered = await agent.call(
    dict[str, int],
    "Keep only genres with more than 1000 movies"
)
```

### Custom Agent Classes

Wrap `Agent` for domain-specific functionality:

```python
from agentica import Agent

class ResearchAgent:
    def __init__(self, web_search_fn):
        self._brain = Agent(
            premise="You are a research assistant.",
            scope={"web_search": web_search_fn}
        )

    async def research(self, topic: str) -> str:
        return await self._brain.call(str, f"Research: {topic}")

    async def summarize(self, text: str) -> str:
        return await self._brain.call(str, f"Summarize: {text}")

# Use it
researcher = ResearchAgent(web_search)
findings = await researcher.research("AI agents in 2025")
summary = await researcher.summarize(findings)
```

### Multi-Agent Orchestration

Coordinate multiple agents for complex tasks:

```python
from agentica import Agent

class LeadResearcher:
    def __init__(self):
        self._brain = Agent(
            premise="Coordinate research tasks across subagents.",
            scope={"SubAgent": ResearchAgent}
        )

    async def __call__(self, query: str) -> str:
        return await self._brain.call(str, query)

# The lead researcher can spawn and coordinate subagents
lead = LeadResearcher()
report = await lead("Research companies building AI agents")
```

Happy programming!

## Content quality standards

- Always include complete, runnable examples that users can copy and execute
- Show proper error handling and edge case management
- Add explanatory comments for complex logic

# Agentica Documentation

## Overview

Agentica is a library for integrating agentic features into TypeScript applications.

## Basics

The primary method of interaction is through the `agentic()` function, which works like this:

```typescript
import { agentic } from '@symbolica/agentica';

// Defines the agent-backed function
async function add(a: number, b: number): Promise<number> {
    return await agentic("Returns the sum of a and b", { a, b });
}

// Calls the agent-backed function
const result = await add(1, 2); // This addition is done by an LLM via the agentica framework
console.assert(result === 3);
```

This allows you to use agents to implement functions which are not possible to implement in pure TypeScript.

The alternative syntax is to `spawn` an agent.

```typescript
import { spawn } from '@symbolica/agentica';

// Spawns the agent
const agent = await spawn({ premise: "You are a truth-teller." });

// Calls the agent
const result: boolean = await agent.call<boolean>("The Earth is flat");
console.assert(result === false);
```

The creation and call of agents created with `spawn` are always awaitable.

### Return Types

Specify return types using TypeScript generics:

```typescript
// Simple call type inferred from explicit annotation
const result: number = await agent.call("What is 2+2?");

// Structured output
interface UserData {
    name: string;
    email: string;
    role: string;
}

// Explicitly passed into generic argument
const user = await agent.call<UserData>("Get user information");
// user is typed as UserData
```

## Model Selection

Agentica supports any text-to-text model available on OpenRouter. Specify with the `model` parameter:

```typescript
// For agents (default is 'openai/gpt-4.1')
const agent = await spawn({ premise: "You are a helpful assistant.", model: "openai/gpt-5" });

// For agentic functions
async function analyze(text: string): Promise<AnalysisResult> {
    return await agentic("Analyze the text", { text }, { model: "anthropic/claude-sonnet-4.5" });
}
```

**Supported models**:
Any OpenRouter model slug (e.g. `google/gemini-2.5-flash`).

## Token Limits

Control the maximum number of tokens generated with `maxTokens`:

```typescript
import { agentic, MaxTokens, spawn } from '@symbolica/agentica';

// For agents
const agent = await spawn({
    premise: "Brief responses only",
    maxTokens: 500  // Limit total output tokens per invocation
});

// For agentic functions
async function summarize(text: string): Promise<string> {
    return await agentic("Create a concise summary", { text }, { maxTokens: 1000 });
}

// For finer control, use MaxTokens:
// - perInvocation: total tokens across all rounds
// - perRound: tokens per inference round
// - rounds: maximum number of inference rounds
const agent2 = await spawn({
    premise: "Brief responses only",
    maxTokens: MaxTokens.from({ perInvocation: 5000, perRound: 1000, rounds: 5 })
});
```

**Use cases**:
- Ensure brief responses for cost control
- Prevent overly long outputs
- Match specific output length requirements

If the response would exceed `maxTokens`, a `MaxTokensError` will be raised. See [Error Handling](#error-handling) for how to handle this.

## Tracking Token Usage

Track token consumption with `lastUsage()` and `totalUsage()` methods on agents:

```typescript
import { spawn } from '@symbolica/agentica';

const agent = await spawn({ premise: "You are helpful." });
await agent.call<string>("Hello!");
await agent.call<string>("How are you?");

// Get usage from the last invocation
const usage = agent.lastUsage();
console.log(`Input tokens:     ${usage.inputTokens}`);
console.log(`Output tokens:    ${usage.outputTokens}`);
console.log(`Cached tokens:    ${usage.cachedTokens}`);
console.log(`Reasoning tokens: ${usage.reasoningTokens}`);

// Get cumulative usage across all invocations
const total = agent.totalUsage();
console.log(`Total: ${total.inputTokens} in, ${total.outputTokens} out, ${total.totalTokens} processed`);

// For agentic functions, use the onUsage callback
async function summarize(text: string): Promise<string> {
    return await agentic("Summarize the text", { text }, {
        onUsage: (usage) => console.log(`Used ${usage.totalTokens} tokens`)
    });
}
```

The `Usage` object contains:
- `inputTokens`: tokens consumed as input
- `outputTokens`: tokens generated as output
- `totalTokens`: total tokens processed (not double-counting re-consumed tokens)
- `cachedTokens`: input tokens served from cache
- `reasoningTokens`: tokens used for internal reasoning

## Initial Prompt vs System Prompt

You can control the agent's instructions in two ways:

```typescript
// Use `premise` (added to default system prompt with environment explainer)
const agent = await spawn({ premise: "You are a math expert." });

// Use `system` for full control of the system prompt (no environment explainer)
const agent = await spawn({ system: "You are a helpful assistant. Always respond with JSON." });
```

**Note**: You cannot use both `premise` and `system` together.

## Passing in objects

If you want the agentic function or agent to use functions, classes, objects etc., simply pass them in the `scope` argument to `call` or `agentic`.

```typescript
import { agentic, spawn } from '@symbolica/agentica';

// User-defined function
import { webSearch } from './tools';

// Defines the agent with scope
const agent = await spawn({ premise: "You are a truth-teller." }, { webSearch });

// Defines the agent-backed function
async function truthTeller(statement: string): Promise<boolean> {
    return await agentic(
        "Returns whether or not this statement is True or False.",
        { statement, webSearch }
    );
}
```

### SDK Integration Pattern

Extract specific methods from SDK clients for focused scope:

```typescript
import { agentic } from '@symbolica/agentica';
import { WebClient } from '@slack/web-api';

// Extract only the methods you need
const slackClient = new WebClient(process.env.SLACK_TOKEN);
const listUsers = slackClient.users.list.bind(slackClient.users);
const postMessage = slackClient.chat.postMessage.bind(slackClient.chat);

async function sendTeamUpdate(message: string): Promise<void> {
    return await agentic(
        "Send `message` to all team members",
        { message, listUsers, postMessage },
        { model: "openai/gpt-5" }
    );
}
```

### Per-Call Scope

You can also add scope for specific invocations:

```typescript
const agent = await spawn({ premise: "Data analyzer" });

// Add resources for this specific call
const result: { [key: string]: number } = await agent.call(
    "Analyze the dataset",
    { dataset, analyzerTool },  // Additional scope
);
```

## Agent Call Signatures

The `agent.call()` method has two signatures:

```typescript
// Simple call with just a prompt
const result = await agent.call<number>("What is 2+2?");

// Call with scope and configuration
const result = await agent.call<object>(
    "Fetch and analyze user data",
    { databaseQuery, apiClient }  // Additional scope
);
```

## Streaming

Streaming model generation is supported for both agents and agentic functions.

### Agent Streaming

```typescript
import { spawn } from '@symbolica/agentica';

// Enable streaming globally for the agent (default for all invocations)
const agent = await spawn({
    premise: "You are a truth-teller.",
    listener: (iid, chunk) => console.log(chunk.content)
});

// Override listener for this invocation specifically
const result = await agent.call<boolean>(
    "Is Paris the capital of France?", {},
    { listener: (iid, chunk) =>  process.stdout.write(chunk.content) }
);
```

Each `Chunk` object contains:
- `content`: the text content of the chunk
- `role`: one of `'user'`, `'agent'`, or `'system'`
- `type`: optional — one of `'reasoning'`, `'output_text'`, `'code'`, `'usage'`, `'invocation_exit'`, or `undefined`

By default, usage chunks (`chunk.type === 'usage'`) are filtered out of the listener stream. To include them, pass `listenerIncludeUsage: true` in the spawn or call config.

### Agentic Function Streaming

Streaming is also supported for agentic functions:

```typescript
async function generateStory(topic: string): Promise<string> {
    return await agentic("Write a story about the topic", { topic }, {
        listener: (iid, chunk) => process.stdout.write(chunk.content)
    });
}
```

## Resource Management

Agents should be properly cleaned up when done.

### Manual Cleanup

```typescript
const agent = await spawn({ premise: "Helper" });
try {
    await agent.call<string>("Do something");
} finally {
    await agent.close();  // Clean up resources
}
```

### Automatic Cleanup with `await using`

Modern TypeScript (5.2+) supports automatic resource disposal:

```typescript
await using agent = await spawn({ premise: "Helper agent" });
// Agent automatically cleaned up when out of scope
const result = await agent.call<string>("Process task");
// No need to call close(), automatically cleaned up at end of scope
```

## Error Handling

Agentica provides comprehensive error handling through the `@symbolica/agentica/errors` module.

### SDK Errors

All Agentica errors inherit from `AgenticaError`, making it easy to catch all SDK-related errors:

```typescript
import { agentic } from '@symbolica/agentica';
import { AgenticaError, RateLimitError, InferenceError } from '@symbolica/agentica/errors';

async function processData(data: string): Promise<object> {
  return agentic<object>("Process the data.", { data });
}

try {
  const result = await processData(rawData);
} catch (e) {
  if (e instanceof RateLimitError) {
    // Handle rate limiting
    await sleep(60000);
    result = await processData(rawData);
  } else if (e instanceof InferenceError) {
    // Handle all inference service errors
    logger.error(`Inference failed: ${e}`);
    result = {};
  } else if (e instanceof AgenticaError) {
    // Catch any other SDK errors
    logger.error(`Agentica error: ${e}`);
    throw e;
  }
}
```

**Error hierarchy:**
- `AgenticaError` - Base for all SDK errors
  - `ServerError` - Base for remote operation errors
    - `GenerationError` - Base for agent generation errors
      - `InferenceError` - HTTP errors from inference service
      - `MaxTokensError`, `ContentFilteringError`, etc.
  - `ConnectionError` - WebSocket and connection errors
  - `InvocationError` - Agent invocation errors

### Custom Exceptions

You can define custom exceptions and pass them into the agentic function's scope so the agent can raise them:

```typescript
/**
 * Raised when input data fails validation.
 */
class DataValidationError extends Error {
  constructor(message: string) {
    super(message);
    this.name = 'DataValidationError';
  }
}

/**
 * Analyze the dataset.
 *
 * @throws {DataValidationError} If data is empty or malformed
 * @throws {Error} If data format is not supported
 */
async function analyzeData(data: string): Promise<object> {
  return agentic<object>(
    `Analyze the dataset.

     Throw DataValidationError if data is empty or malformed.
     Throw Error if data format is not supported.

     Return analysis results.`,
    { data, DataValidationError }
  );
}

try {
  const result = await analyzeData(rawData);
} catch (e) {
  if (e instanceof DataValidationError) {
    logger.warn(`Invalid data: ${e}`);
    result = { status: "validation_failed" };
  }
}
```

**Tip**: The agent can see your JSDoc comments (`/** ... */`)! Document exception conditions clearly using `@throws` tags, and also include them in your prompt. The agent will raise them appropriately.

## Common Patterns

### Stateful Conversations

Agents maintain context across calls:

```typescript
const assistant = await spawn({ premise: "You are a helpful coding assistant." });

// First interaction
await assistant.call<void>("My name is Alice and I'm learning TypeScript");

// Later interaction - agent remembers context
const response = await assistant.call<string>("What's my name?");
console.log(response); // "Your name is Alice"
```

### Custom Agent Classes

Wrap agents for domain-specific functionality:

```typescript
import { Agent, spawn } from '@symbolica/agentica';

class ResearchAssistant {
    private agent: Agent | null = null;

    constructor(private webSearch: (query: string) => Promise<any>) { }

    async initialize(): Promise<void> {
        this.agent = await spawn(
            { premise: "You are a research assistant." },
        );
    }

    async research(topic: string): Promise<string> {
        return await this.agent!.call<string>(
            "Research the topic",
            { topic, webSearch: this.webSearch }
        );
    }

    async summarize(text: string): Promise<string> {
        return await this.agent!.call<string>(
            "Summarize this text",
            { text }
        );
    }

    async close(): Promise<void> {
        await this.agent?.close();
    }
}

// Usage
const researcher = new ResearchAssistant(myWebSearchFn);
await researcher.initialize();
const findings = await researcher.research("AI agents in 2025");
const summary = await researcher.summarize(findings);
await researcher.close();
```

### Resource Management Pattern

Modern pattern for automatic cleanup:

```typescript
async function processTask(task: string): Promise<string> {
    await using agent = await spawn({
        premise: "Task processor",
        model: "openai/gpt-5"
    });

    const result = await agent.call<string>(task);
    return result;
    // Agent automatically cleaned up here
}
```

## Multi-Agent Orchestration

Coordinate multiple agents for complex tasks by wrapping agents in custom classes.

### Pattern: Lazy Agent Initialization

Defer agent creation until first use:

```typescript
import { Agent, spawn } from '@symbolica/agentica';

class ResearchAgent {
    private brain: Agent | null = null;

    private async ensureBrain(): Promise<Agent> {
        if (this.brain === null) {
            this.brain = await spawn({
                premise: "You are a research assistant.",
                model: "openai/gpt-4o"
            });
        }
        return this.brain;
    }

    async research(topic: string): Promise<string> {
        const brain = await this.ensureBrain();

        // Bind instance methods for agent scope
        const webSearch = this.webSearch.bind(this);

        return await brain.call<string>(
            "Research the topic",
            { topic, webSearch } // Pass bound methods
        );
    }

    private async webSearch(query: string): Promise<any> {
        // [implementation omitted]
        return { results: [] };
    }

    async close(): Promise<void> {
        if (this.brain !== null) {
            await this.brain.close();
        }
    }
}
```

### Pattern: Multi-Agent Coordination

Coordinate multiple specialized agents:

```typescript
class CitationAgent { ... }

class DeepResearchSession {
    private leadResearcher: Agent | null = null;
    private citationAgent: CitationAgent;

    constructor(private directory: string) {
        this.citationAgent = new CitationAgent(directory);
    }

    private async ensureLeadResearcher(): Promise<Agent> {
        if (this.leadResearcher === null) {
            this.leadResearcher = await spawn({
                premise: "You are a lead researcher. Coordinate subagents to research the query.",
                model: "openai/gpt-4o"
            });
        }
        return this.leadResearcher;
    }

    async run(query: string): Promise<string> {
        const leader = await this.ensureLeadResearcher();

        // Lead researcher can spawn and coordinate SubAgent instances
        const report: string = await leader.call(
            query,
            {
                SubAgent,  // Pass the class itself
                savePlan: (plan: string) => this.savePlan(plan),
                loadPlan: () => this.loadPlan()
            },
            { listener: (iid, chunk) => process.stdout.write(chunk.content) }
        );

        // Post-process with citation agent
        await this.citationAgent.run(report);

        return `Research complete! Check ${this.directory}/report.md`;
    }

    private async savePlan(plan: string): Promise<void> {
        // Save to directory
    }

    private async loadPlan(): Promise<string> {
        // Load from directory
        return "";
    }

    async close(): Promise<void> {
        if (this.leadResearcher !== null) {
            await this.leadResearcher.close();
        }
        await this.citationAgent.close();
    }
}

// Usage
const session = new DeepResearchSession('research_output');
try {
    const result = await session.run("Research AI agents in 2025");
    console.log(result);
} finally {
    await session.close();
}
```

### Pattern: SubAgent with Instance Counter

Create multiple agent instances with unique IDs:

```typescript
let idGen = 0;

class SubAgent {
    id: number;
    private brain: Agent | null = null;

    constructor(private directory: string) {
        this.id = idGen++;  // Unique ID per instance
    }

    private async ensureBrain(): Promise<Agent> {
        if (this.brain === null) {
            this.brain = await spawn({
                premise: "You are a specialized research agent.",
                model: "openai/gpt-4o"
            });
        }
        return this.brain;
    }

    async run(task: string): Promise<string> {
        const brain = await this.ensureBrain();

        // Bind methods for scope
        const saveResults = this.saveResults.bind(this);

        const result: string = await brain.call(
            task,
            { saveResults },
            { listener: (iid, chunk) => process.stdout.write(`[SubAgent ${this.id}] ${chunk.content}`) }
        );

        return result;
    }

    private async saveResults(data: any): Promise<void> {
        // Save with unique path using this.id
        const path = `${this.directory}/subagent_${this.id}/results.json`;
        // ... save logic
    }

    async close(): Promise<void> {
        if (this.brain !== null) {
            await this.brain.close();
        }
    }
}
```

### Best Practices for Multi-Agent Systems

1. **Lazy Initialization**: Create agents only when needed using `ensureBrain()` pattern
2. **Resource Cleanup**: Always implement `close()` and call it in `finally` blocks
3. **Method Binding**: Use `.bind(this)` when passing instance methods to agent scope
4. **Unique IDs**: Use counters or UUIDs for agent identification
5. **Streaming Coordination**: Stream nested agent outputs for visibility
6. **Error Handling**: Wrap agent calls in try/finally for proper cleanup
7. **Type Safety**: Use TypeScript generics for type-safe agent responses

```typescript
// Complete example with best practices
class RobustAgentWrapper {
    private agent: Agent | null = null;

    private async ensureAgent(): Promise<Agent> {
        if (this.agent === null) {
            this.agent = await spawn({
                premise: "Task executor",
                model: "openai/gpt-5"
            });
        }
        return this.agent;
    }

    async execute<T>(task: string, tools: object = {}): Promise<T> {
        const agent = await this.ensureAgent();

        try {
            const result: T = await agent.call<T>(
                task,
                tools,
                { listener: (iid, chunk) => console.log(chunk.content) }
            );

            return result;
        } catch (error) {
            console.error('Agent execution failed:', error);
            throw error;
        }
    }

    async close(): Promise<void> {
        if (this.agent) {
            await this.agent.close();
            this.agent = null;
        }
    }
}

// Usage with automatic cleanup
async function processTask(): Promise<string> {
    const wrapper = new RobustAgentWrapper();
    try {
        const result = await wrapper.execute<string>("Analyze data");
        return result;
    } finally {
        await wrapper.close();
    }
}
```

## Logging and Debugging

<Note>
**More advanced listener support on par with Python is coming soon to TypeScript.**

Logging and listener functionality is currently restricted to callback-style listeners in TypeScript.
</Note>

### Current Debugging Options

For now, you can observe agent behavior through:

```typescript
// 1. Streaming responses for real-time observation
const result = await agent.call<string>("Complex task", {}, {
    listener: (iid, chunk) => console.log('[Agent]:', chunk.content)
});

// 2. Standard console logging
console.log('Agent returned:', result);
```

Happy programming!

## Content quality standards

- Always include complete, runnable examples that users can copy and execute
- Show proper error handling and edge case management
- Add explanatory comments for complex logic

Getting Started

Core Concepts

Guides

Integrations

Prerequisites

Project rules

​Prerequisites

​Project rules

Prerequisites

Project rules