Aiceberg with Agentic Frameworks

TL;DR

Agent frameworks orchestrate complex execution flows—multiple steps, LLM calls, external tool calls, custom memory access—that, when unobserved, can compound into significant failures or misalignment.

Add Aiceberg observability to your agent framework by exposing discrete lifecycle events and forwarding them to Aiceberg through a simple callback to enforce a spider-web layer of safety and security across every event—LLM calls, tool usage and inputs, and multi-agent interactions and memory access end-to-end.

How Aiceberg Fits Into an Event-Driven Agent Framework

Aiceberg integrates cleanly into any agent framework, whether it emits native events or not.

Either approach provides seamless, end-to-end safety and security coverage across the entire agent workflow.

If Your Framework Exposes Discrete Events

The simplest integration is when your framework already emits events such as agent_start, llm_call_end, or tool_call_start.

Aiceberg hooks into these points with a lightweight callback, making observability simple:

event → callback → send to Aiceberg → safety & security analysis → continue/block execution

This gives full visibility across all model calls, tools (MCP or custom), memory access, and agent-to-agent interactions.

If Your Framework Doesn’t Expose Events Yet

You can still integrate Aiceberg by wrapping critical operations—LLM calls, tool invocations, memory access—with decorators or interceptors.

These wrappers capture inputs, outputs, metadata, and context and forward them to Aiceberg just like native events.

Aiceberg’s Event Model for End-to-End Agent Workflows

Aiceberg defines five core event types that cover the entire agent lifecycle:

• user → agent

• agent → LLM

• agent → tool (MCP or custom)

• agent → memory

• agent → agent (multi-agent or delegated calls)

Most modern agent frameworks already follow a very similar interaction pattern. For example, AWS Strands exposes a hook event lifecycle that neatly aligns with the above events. Here’s a detailed document on how to integrate Aiceberg’s observability into AWS Strands with just one block of code:

strands_integration.py

from ab_strands_samples.aiceberg_monitor import StrandsAicebergHandler

agent = Agent(
    system_prompt=""
    model=model,
    tools=math_tools,
    hooks=[StrandsAicebergHandler()],
)

How to Add Aiceberg-Style Hooks to Your Own Framework

Below are the three steps needed to support Aiceberg observability natively in your custom agent framework:

1

Step 1: Check if your framework exposes events

First, confirm whether your framework already has a way to observe internal activity, such as:

• Lifecycle hooks (on_agent_start, on_llm_end, on_tool_start, etc.)

• Middleware/interceptors around agent runs, tools, or models

• An internal event bus or signal system

If these exist, you can plug Aiceberg in directly. If not, you’ll need to introduce simple event emission at key points (user→agent, agent→LLM, agent→tool, agent→memory, agent→agent).

2

Step 2: Identify (or create) the registry for callbacks

You need a central place where users can register handlers for those events, similar to Strands’ hooks or a HookRegistry:

• This can be a hooks=[...] list on the agent

• Or a middleware stack that is run on every step/call

The goal: have a single, predictable place where an AicebergHandler can be attached.

3

Step 3: Define callbacks per event to call Aiceberg (and optionally block)

Each callback should perform the following sub-steps to integrate with Aiceberg’s API:

1

Initiate session

Initiate the session with a unique session_id that groups all the interactions between different participants of that workflow. Maintain this session_id consistently across all emitted events.

2

Consume the event input and context

Capture relevant data for the event: user message, prompt, tool name, parameters, memory payload, etc.

3

Send it to Aiceberg for analysis

Call the Aiceberg API with the event payload (see endpoint and payload examples below). Based on Aiceberg’s response, you may allow, modify, redact, or block execution.

Endpoint and Headers

Endpoint:

Get base URL from customer success team during onboarding.

base_url/eap/v1/event

Headers:

{
  "Authorization": "AICEBERG_API_KEY"
}

Payload Structure

event_payload.json

{
  "input": "event content", // can be llm prompt, tool inputs, memory write item
  "profile_id": "01JZ5ZA2CVNDD9SEAZA53KZSZV", // when using a single profile
  "use_case_id": "01JZ5ZA2CVNDD9SEAZA53KZSZV", // when using multiple profiles
  "event_type": "agt_llm",
  "session_id": "01K6ZH5J8TH9GS2CJWD1VF6TJ2",
  "metadata": {"user_id": "planner_agent"},
  "forward_to_llm": false
}

Parameter Summary

• input: Full input or output of the event.

• profile_id: When using a single monitoring profile.

• use_case_id: When using multiple monitoring profiles / dedicated profile per event type.

• event_type: user_agt, agt_llm, agt_tool, agt_mem, agt_agent.

• session_id: Unique per user session, consistent across all events.

• metadata.user_id: Name of agent or user.

• forward_to_llm: false = listen, true = enforce.

Use Aiceberg’s Response to Control Flow

• event_result determines pass or block.

• If PII is detected, Aiceberg returns a redacted version in prompt.

• original_prompt preserves the unredacted content.

• You may block, modify, redact, or allow the execution based on these signals.

In practice, each callback becomes a lightweight guardrail gating the further execution of the agentic flow.

Conclusion

Expose events, attach one handler, and Aiceberg does the rest—monitoring safety, security, PII, and alignment across every part of your agent workflow.