Lifecycle hooks

Lifecycle hooks let you customize agent behavior at key execution points. Use hooks for logging, validation, or modifying inputs/outputs.

What are lifecycle hooks?

Hooks are functions that run at specific stages of agent execution:

on_start - Before agent execution begins
on_end - After agent execution completes
on_agent_step_start - Before each agent reasoning step
on_agent_step_end - After each agent reasoning step
on_tool_start - Before each tool execution
on_tool_end - After each tool execution

Defining hooks

Create hooks using the @hook decorator in Python or the defineHook function in TypeScript:

from polos import hook, WorkflowContext, HookContext, HookResult

@hook
def log_hook(ctx: WorkflowContext, hook_context: HookContext) -> HookResult:
    """Log execution details."""
    print(f"Workflow: {hook_context.workflow_id}")
    print(f"Payload: {hook_context.current_payload}")

    return HookResult.continue_with()

import { defineHook, HookResult } from '@polos/sdk';
import type { HookResultType } from '@polos/sdk';

const logHook = defineHook(async (ctx, hookCtx): Promise<HookResultType> => {
  console.log(`Workflow: ${hookCtx.workflowId}`);
  console.log(`Payload: ${JSON.stringify(hookCtx.currentPayload)}`);

  return HookResult.continue();
}, { name: 'logHook' });

Hook signature:

ctx - WorkflowContext with execution metadata
hook_context - HookContext with current execution state
Returns - HookResult indicating what action to take

Hook results

Hooks return HookResult with three options:

1. Continue without changes

@hook
def simple_hook(ctx: WorkflowContext, hook_context: HookContext) -> HookResult:
    # Just observe, don't modify
    print("Hook executed")
    return HookResult.continue_with()

import { defineHook, HookResult } from '@polos/sdk';
import type { HookResultType } from '@polos/sdk';

const simpleHook = defineHook(async (ctx, hookCtx): Promise<HookResultType> => {
  // Just observe, don't modify
  console.log('Hook executed');
  return HookResult.continue();
}, { name: 'simpleHook' });

2. Continue with modifications

import re

@hook
def redact_pii_hook(ctx: WorkflowContext, hook_context: HookContext) -> HookResult:
    """Redact sensitive information from payloads."""
    if not hook_context.current_payload:
        return HookResult.continue_with()

    modified = hook_context.current_payload.copy()

    # Redact emails
    if isinstance(modified, dict):
        for key, value in modified.items():
            if isinstance(value, str):
                modified[key] = re.sub(
                    r'\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b',
                    '[EMAIL_REDACTED]',
                    value
                )

    return HookResult.continue_with(modified_payload=modified)

import { defineHook, HookResult } from '@polos/sdk';
import type { HookResultType } from '@polos/sdk';

const redactPiiHook = defineHook(async (ctx, hookCtx): Promise<HookResultType> => {
  /** Redact sensitive information from payloads. */
  if (!hookCtx.currentPayload) {
    return HookResult.continue();
  }

  const modified = { ...hookCtx.currentPayload };

  // Redact emails
  const emailRegex = /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b/g;
  for (const key of Object.keys(modified)) {
    if (typeof modified[key] === 'string') {
      modified[key] = modified[key].replace(emailRegex, '[EMAIL_REDACTED]');
    }
  }

  return HookResult.continueWith({ modifiedPayload: modified });
}, { name: 'redactPiiHook' });

3. Fail and stop execution

@hook
def validation_hook(ctx: WorkflowContext, hook_context: HookContext) -> HookResult:
    """Validate payload before execution."""
    payload = hook_context.current_payload

    if not payload or not payload.get("required_field"):
        return HookResult.fail("Missing required field")

    return HookResult.continue_with()

import { defineHook, HookResult } from '@polos/sdk';
import type { HookResultType } from '@polos/sdk';

const validationHook = defineHook(async (ctx, hookCtx): Promise<HookResultType> => {
  /** Validate payload before execution. */
  const payload = hookCtx.currentPayload;

  if (!payload || !payload.requiredField) {
    return HookResult.fail('Missing required field');
  }

  return HookResult.continue();
}, { name: 'validationHook' });

Using hooks

Attach hooks to agents:

from polos import Agent

tracked_agent = Agent(
    id="tracked-agent",
    provider="openai",
    model="gpt-4o",
    system_prompt="You are a helpful assistant.",
    tools=[search, send_email],

    # Workflow hooks
    on_start=[log_hook, validate_input_hook],
    on_end=[log_hook, save_results_hook],

    # Step hooks
    on_agent_step_start=[log_step_hook],
    on_agent_step_end=[validate_step_hook],

    # Tool hooks
    on_tool_start=[log_tool_call_hook],
    on_tool_end=[audit_tool_result_hook]
)

import { defineAgent } from '@polos/sdk';

const trackedAgent = defineAgent({
  id: 'tracked-agent',
  model: 'gpt-4o',
  systemPrompt: 'You are a helpful assistant.',
  tools: [search, sendEmail],

  // Workflow hooks
  onStart: [logHook, validateInputHook],
  onEnd: [logHook, saveResultsHook],

  // Step hooks
  onAgentStepStart: [logStepHook],
  onAgentStepEnd: [validateStepHook],

  // Tool hooks
  onToolStart: [logToolCallHook],
  onToolEnd: [auditToolResultHook],
});

Hook context

Hooks receive HookContext with execution state:

@hook
def inspect_context_hook(ctx: WorkflowContext, hook_context: HookContext) -> HookResult:
    # Workflow information
    workflow_id = hook_context.workflow_id

    # User context
    user_id = hook_context.user_id
    session_id = hook_context.session_id

    # Execution state
    current_payload = hook_context.current_payload
    current_output = hook_context.current_output
    current_tool = hook_context.current_tool

    # Agent configuration
    agent_config = hook_context.agent_config

    # Step history
    steps = hook_context.steps  # List of completed steps

    return HookResult.continue_with()

import { defineHook, HookResult } from '@polos/sdk';
import type { HookResultType } from '@polos/sdk';

const inspectContextHook = defineHook(async (ctx, hookCtx): Promise<HookResultType> => {
  // Workflow information
  const workflowId = hookCtx.workflowId;

  // User context
  const userId = hookCtx.userId;
  const sessionId = hookCtx.sessionId;

  // Execution state
  const currentPayload = hookCtx.currentPayload;
  const currentOutput = hookCtx.currentOutput;
  const currentTool = hookCtx.currentTool;

  // Agent configuration
  const agentConfig = hookCtx.agentConfig;

  // Step history
  const steps = hookCtx.steps; // Array of completed steps

  return HookResult.continue();
}, { name: 'inspectContextHook' });

Multiple hooks

Hooks run in order. If any hook fails, execution stops:

agent = Agent(
    id="multi-hook-agent",
    provider="openai",
    model="gpt-4o",
    on_start=[
        validate_input_hook,     # Runs first
        redact_pii_hook,         # Runs second (on validated input)
        add_metadata_hook        # Runs third (on redacted input)
    ]
)

import { defineAgent } from '@polos/sdk';

const agent = defineAgent({
  id: 'multi-hook-agent',
  model: 'gpt-4o',
  onStart: [
    validateInputHook,   // Runs first
    redactPiiHook,       // Runs second (on validated input)
    addMetadataHook,     // Runs third (on redacted input)
  ],
});

If validate_input_hook fails, redact_pii_hook and add_metadata_hook never run.

Hook execution flow

Complete agent execution with hooks:

Introduction

Getting Started

Fundamentals

Agents

Workflows

Observability

Guides and Examples

Community

What are lifecycle hooks?

Defining hooks

Hook results

1. Continue without changes

2. Continue with modifications

3. Fail and stop execution

Using hooks

Hook context

Multiple hooks

Hook execution flow

​What are lifecycle hooks?

​Defining hooks

​Hook results

​1. Continue without changes

​2. Continue with modifications

​3. Fail and stop execution

​Using hooks

​Hook context

​Multiple hooks

​Hook execution flow

What are lifecycle hooks?

Defining hooks

Hook results

1. Continue without changes

2. Continue with modifications

3. Fail and stop execution

Using hooks

Hook context

Multiple hooks

Hook execution flow