Skip to main content

​
Overview

The Agent Core module provides the central agent loop functionality, handling message processing, tool execution, and agent lifecycle management. It orchestrates LLM calls, tool invocations, and context management.

​
Main Functions

​
agent::chat

Process a message through the complete agent loop with validation, security checks, tool execution, and response generation.
​
input
ChatRequest
required
The chat request object containing:
​
agentId
string
required
The unique identifier of the agent
​
message
string
required
The user message to process
​
sessionId
string
Optional session identifier for conversation continuity
​
systemPrompt
string
Optional system prompt override
​
ChatResponse
object
​
content
string
The agent’s response content
​
model
string
The model used for generation
​
usage
object
Token usage statistics (input, output, cacheRead, cacheWrite)
​
iterations
number
Number of tool execution iterations performed

​
Process Flow

The agent::chat function executes the following steps:
  1. Request Validation - Validates agentId and checks rate limits
  2. Concurrent Slot Acquisition - Ensures agent doesn’t exceed concurrent request limits
  3. Context Preparation - Loads agent config, recalls memories, and prepares tools
  4. Security Scanning - Scans for injection attacks (blocks if riskScore > 0.5)
  5. Budget Checking - Verifies agent hasn’t exceeded token/cost budgets
  6. LLM Execution - Calls the LLM with messages and available tools
  7. Tool Loop - Executes tool calls iteratively (max 50 iterations)
  8. Response Recording - Stores conversation in memory and updates metrics
import { trigger } from 'iii-sdk';

const response = await trigger('agent::chat', {
  agentId: 'agent-123',
  message: 'What files are in the workspace?',
  sessionId: 'session-abc'
});

console.log(response.content);
console.log(`Used ${response.iterations} tool iterations`);

​
Constants

  • MAX_ITERATIONS: 50 - Maximum tool execution iterations
  • TOOL_TIMEOUT_MS: 120,000 - Tool execution timeout (2 minutes)
  • MAX_CHAT_TIMEOUT_MS: 300,000 - Overall chat timeout (5 minutes)
  • CONTEXT_HEALTH_CHECK_INTERVAL: 10 - Check context health every N iterations
  • CONTEXT_HEALTH_THRESHOLD: 60 - Compress context if health score < threshold

​
agent::list_tools

List all tools available to a specific agent based on its capabilities and tool profile.
​
agentId
string
required
The agent identifier to list tools for
​
tools
array
Array of tool definitions with function_id, description, and metadata
const tools = await trigger('agent::list_tools', {
  agentId: 'agent-123'
});

console.log(`Agent has access to ${tools.length} tools`);

​
agent::create

Register a new agent with configuration and capabilities.
​
config
AgentConfig
required
​
id
string
Optional agent ID (auto-generated if not provided)
​
name
string
Agent name
​
systemPrompt
string
Default system prompt for the agent
​
capabilities
object
​
tools
string[]
Allowed tool prefixes (e.g., [“tool::”, “agent::”] or [”*”] for all)
​
toolProfile
string
Tool filtering profile: “full”, “minimal”, or custom
​
codeAgentMode
boolean
Enable automatic code detection and execution
​
agentId
string
The created agent’s unique identifier
const { agentId } = await trigger('agent::create', {
  name: 'Code Assistant',
  systemPrompt: 'You are a helpful coding assistant.',
  capabilities: {
    tools: ['tool::file_read', 'tool::file_write', 'tool::shell_exec']
  },
  toolProfile: 'full',
  codeAgentMode: true
});

console.log(`Created agent: ${agentId}`);

​
agent::list

List all registered agents.
​
agents
array
Array of agent configurations

​
agent::delete

Remove an agent from the system.
​
agentId
string
required
The agent identifier to delete
​
deleted
boolean
Confirmation of deletion

​
agent::list_by_division

List agents filtered by division (organizational grouping).
​
division
Division
Optional division filter (e.g., “engineering”, “support”)
​
agents
array
Filtered array of agents

​
Internal Functions

These functions are used internally by the agent loop:

​
validateRequest

Validates the chat request, checks rate limits, and acquires concurrent execution slots. Location: agent-core.ts:43

​
prepareContext

Prepares the execution context by loading agent config, recalling memories, listing tools, routing to appropriate model, and scanning for security threats. Location: agent-core.ts:95

​
executeLlmCall

Executes a single LLM completion call with the current messages and tools, recording replay events and tracking token costs. Location: agent-core.ts:162

​
executeToolCall

Executes a single tool call with comprehensive security checks including guard policies, approval requirements, capability verification, and policy enforcement. Location: agent-core.ts:291 Security Checks Performed:
  1. Tool allowlist verification
  2. Guard circuit breaker check
  3. Approval tier decision (sync/async)
  4. Policy enforcement
  5. Capability verification

​
toolLoop

Executes the iterative tool calling loop, handling multiple rounds of tool execution until the agent produces a final response or reaches MAX_ITERATIONS. Location: agent-core.ts:484 Features:
  • Automatic context health monitoring
  • Context compression when health degrades
  • Audit logging for each iteration
  • Tool result injection into message history

​
handleCodeAgent

Detects and executes code blocks when codeAgentMode is enabled, automatically running code and feeding results back into the conversation. Location: agent-core.ts:213

​
Configuration

The agent core connects to the engine via the ENGINE_URL environment variable and registers as the “agent-core” worker.

​
Hooks and Events

The agent loop fires several hooks that can be listened to:
  • BeforeToolCall - Fired before each tool execution
  • AfterToolCall - Fired after successful tool execution
  • AgentLoopEnd - Fired when the agent loop completes

​
Metrics

The agent core records the following metrics:
  • active_sessions - Current active chat sessions (gauge)
  • tokens_used_total - Total tokens consumed (input/output)
  • tool_execution_total - Tool execution counts by status
  • function_call_duration_ms - Call duration histogram
  • function_error_total - Error counts by type

Build docs developers (and LLMs) love

Get started for freeTalk to us