Agents

Agents provide an agentic loop that automatically handles tool execution, enabling autonomous task completion.

Overview

The Agent class implements a complete agentic workflow:

1. Send prompt to LLM

2. LLM may request tool calls

3. Execute tools automatically

4. Send results back to LLM

5. Repeat until task complete or limits reached

Creating an Agent

import { AgenticWork } from '@agentic-work/sdk';

const aw = new AgenticWork({
  apiEndpoint: 'https://api.agenticwork.io',
  authToken: process.env.AGENTICWORK_TOKEN
});

await aw.init();

const agent = aw.createAgent({
  model: 'gpt-4o',
  systemPrompt: 'You are a helpful coding assistant.',
  tools: aw.getMCPTools(),
  maxIterations: 10,
  maxToolCalls: 25,
  onToolCall: (tc) => console.log('Tool called:', tc.name),
  onToolResult: (tr) => console.log('Tool result:', tr.content.slice(0, 100)),
  onText: (text) => process.stdout.write(text)
});

Configuration Options

Option	Type	Default	Description
model	string	Required	LLM model to use
systemPrompt	string	Built-in	Custom system prompt
tools	Tool[]	[]	Tools available to the agent
maxIterations	number	10	Maximum LLM call rounds
maxToolCalls	number	25	Maximum total tool executions
onToolCall	function	-	Callback when tool is invoked
onToolResult	function	-	Callback when tool completes
onText	function	-	Callback for each text chunk

Running an Agent

Streaming Execution

// Stream text output as it's generated
for await (const text of agent.run({
  prompt: 'Create a Python script that downloads a webpage'
})) {
  process.stdout.write(text);
}

Non-Streaming Execution

const result = await agent.execute({
  prompt: 'Fix the bug in utils.ts'
});

console.log('Final response:', result.finalResponse);
console.log('Tool calls made:', result.toolCallCount);
console.log('Total tokens:', result.usage?.totalTokens);

Agent Result

The execute() method returns an AgentResult:

interface AgentResult {
  messages: Message[];      // Full conversation history
  finalResponse: string;    // Final text response
  toolCallCount: number;    // Number of tools executed
  usage?: TokenUsage;       // Token usage statistics
}

Using Platform MCP Tools

// Get all available MCP tools
const allTools = aw.getMCPTools();

// Filter specific tools
const webTools = allTools.filter(t => t.name.startsWith('awp_web'));
const fileTools = allTools.filter(t =>
  ['read_file', 'write_file', 'list_files'].some(n => t.name.includes(n))
);

const agent = aw.createAgent({
  model: 'gpt-4o',
  tools: [...webTools, ...fileTools]
});

Adding Custom Tools

import { z } from 'zod';
import type { Tool } from '@agentic-work/sdk';

const customTool: Tool = {
  name: 'database_query',
  description: 'Execute a SQL query against the database',
  inputSchema: z.object({
    query: z.string().describe('SQL query to execute'),
    database: z.string().optional().describe('Database name')
  }),
  execute: async (args, context) => {
    const { query, database } = args as { query: string; database?: string };
    // Execute query...
    return JSON.stringify({ rows: [], affected: 0 });
  }
};

// Add to agent
agent.addTool(customTool);

// Or include at creation
const agent = aw.createAgent({
  model: 'gpt-4o',
  tools: [...aw.getMCPTools(), customTool]
});

Tool Context

Tools receive a context object with useful utilities:

interface ToolContext {
  workingDirectory: string;  // Current working directory
  signal: AbortSignal;       // For cancellation
  onProgress?: (output: string) => void;  // Stream progress
}

Use context in tool execution:

const myTool: Tool = {
  name: 'long_running_task',
  description: 'A task that takes a while',
  inputSchema: z.object({ input: z.string() }),
  execute: async (args, context) => {
    // Check for cancellation
    if (context.signal.aborted) {
      throw new Error('Cancelled');
    }

    // Report progress
    context.onProgress?.('Starting task...');

    // Use working directory
    const filePath = path.join(context.workingDirectory, 'output.txt');

    return 'Task complete';
  }
};

Removing Tools

// Remove a tool by name
agent.removeTool('database_query');

Updating Agent Configuration

// Change model
agent.setModel('claude-3-5-sonnet-20241022');

// Update system prompt
agent.setSystemPrompt('You are now a Python expert.');

Default System Prompt

If no system prompt is provided, agents use:

You are an AI coding assistant. You help developers by:
- Reading, writing, and editing files
- Running shell commands
- Searching codebases
- Explaining code

Guidelines:
- Be concise and direct
- Use tools to gather information before making assumptions
- After completing a task, summarize what was done in text
- Do NOT keep calling tools after the task is complete

Callbacks for Observability

const agent = aw.createAgent({
  model: 'gpt-4o',
  tools: aw.getMCPTools(),

  onToolCall: (toolCall) => {
    console.log(`[TOOL] ${toolCall.name}`);
    console.log(`[ARGS] ${JSON.stringify(toolCall.arguments)}`);
  },

  onToolResult: (result) => {
    const preview = result.content.slice(0, 200);
    console.log(`[RESULT] ${result.isError ? 'ERROR: ' : ''}${preview}`);
  },

  onText: (text) => {
    // Real-time text streaming
    process.stdout.write(text);
  }
});

Error Handling

try {
  const result = await agent.execute({
    prompt: 'Do something complex'
  });
} catch (error) {
  if (error.message.includes('max iterations')) {
    console.log('Agent reached iteration limit');
  } else if (error.message.includes('max tool calls')) {
    console.log('Agent reached tool call limit');
  } else {
    console.error('Agent error:', error.message);
  }
}

Best Practices

1. Set appropriate limits - Adjust maxIterations and maxToolCalls based on task complexity

2. Use callbacks - Monitor agent progress with onToolCall and onToolResult

3. Provide clear prompts - Specific prompts lead to better results

4. Filter tools - Only provide tools relevant to the task

5. Handle errors - Implement proper error handling for production use