Operation Methods

Record tool calls, agent spawning, memory access, and external API calls.

Operation events are Tier 3 in the AOP spec. They capture what the agent does in the external world — every tool invocation, every API call, every child agent.

toolStart()

Emits an operation.tool_start event. Returns a toolCallId string to correlate with toolEnd().

aop.toolStart(
  toolName: string,
  input?: Record<string, unknown>,
  metadata?: Record<string, unknown>
): string  // returns toolCallId

Example

const callId = await aop.toolStart('web_search', {
  query: 'AOP protocol specification'
})

const results = await webSearch('AOP protocol specification')

await aop.toolEnd('web_search', true, `Found ${results.length} results`, 350, {
  toolCallId: callId
})

toolEnd()

Emits an operation.tool_end event. Pair with toolStart() using the returned toolCallId.

aop.toolEnd(
  toolName: string,
  success: boolean,
  resultSummary?: string,
  durationMs?: number,
  options?: {
    toolCallId?: string
    metadata?: Record<string, unknown>
  }
): void

Example

// Successful tool call
await aop.toolEnd('web_search', true, 'Found 12 results', 420, {
  toolCallId: callId
})

// Failed tool call
await aop.toolEnd('database_query', false, 'Connection timeout', 5000, {
  toolCallId: callId
})

agentSpawn()

Emits an operation.agent_spawn event and returns a new session ID for the child agent.

aop.agentSpawn(
  childAgentId: string,
  options?: {
    goal?: string
    metadata?: Record<string, unknown>
  }
): string  // returns childSessionId

Example

const childSessionId = await aop.agentSpawn('research-agent', {
  goal: 'Find recent papers on transformer architectures'
})

// Pass childSessionId to the child agent process
spawnChildAgent({
  agentId: 'research-agent',
  sessionId: childSessionId,
  parentSessionId: aop.sessionId
})

See Multi-agent sessions for the full parent-child linking pattern.

memory()

Emits an operation.memory event. Tracks reads, writes, and deletes to the agent's memory or knowledge store.

aop.memory(
  operation: 'read' | 'write' | 'delete',
  options?: {
    key?: string
    summary?: string
    metadata?: Record<string, unknown>
  }
): void

Example

// Writing to memory
await aop.memory('write', {
  key: 'user_preferences',
  summary: 'Stored user preference for concise responses'
})

// Reading from memory
await aop.memory('read', {
  key: 'conversation_history',
  summary: 'Retrieved last 10 messages for context'
})

// Deleting from memory
await aop.memory('delete', {
  key: 'stale_cache',
  summary: 'Cleared expired cache entries'
})

externalCall()

Emits an operation.external_call event. Use this for HTTP or API calls that are not tool invocations — direct fetch calls, webhook deliveries, etc.

aop.externalCall(
  method: string,
  url: string,
  options?: {
    statusCode?: number
    durationMs?: number
    metadata?: Record<string, unknown>
  }
): void

Example

await aop.externalCall('POST', 'https://api.openai.com/v1/chat/completions', {
  statusCode: 200,
  durationMs: 1200,
  metadata: { model: 'gpt-4', tokens: 1500 }
})

await aop.externalCall('GET', 'https://api.github.com/repos/useaop/aop-spec', {
  statusCode: 404,
  durationMs: 89
})

Related