@agentic-eng/observability

Observability implementations for the Agentic Engineering Framework.

Part of the Agentic Engineering Framework

The Agentic Engineering Framework is a minimal, type-safe TypeScript framework for building LLM-powered agent systems. It provides building blocks for agents that can reason, use tools, persist knowledge, and emit observable events — with zero LLM lock-in.

| Package | Description | | --- | --- | | @agentic-eng/agent | Agent class and reasoning loop — start here | | @agentic-eng/core | Shared types, enums, and error classes | | @agentic-eng/provider | Interface-only contracts (LlmProvider, MemoryProvider, ObservabilityProvider) | | @agentic-eng/tool | Tool interface and ToolRegistry | | @agentic-eng/memory | Memory implementations (FlatFileMemory) | | @agentic-eng/observability (this package) | Observability implementations (ConsoleObserver, NoopObserver) |

What This Package Does

@agentic-eng/observability provides concrete implementations of the ObservabilityProvider interface from @agentic-eng/provider. Observability lets you monitor every lifecycle event in the agent — from invoke start/end to individual LLM calls, tool executions, and memory stores.

Currently ships:

• ConsoleObserver — formatted console logging for development and debugging
• NoopObserver — silently discards all events (used internally as default when no observer is configured)

Installation

npm install @agentic-eng/observability

Prerequisite: You also need @agentic-eng/agent to use observability with an agent.

Using ConsoleObserver with the Agent

import { Agent } from '@agentic-eng/agent';
import { ConsoleObserver } from '@agentic-eng/observability';

const agent = new Agent({
  name: 'assistant',
  provider: myProvider,
  observability: new ConsoleObserver(),
});

await agent.invoke('What is 42 × 17?');

Console output:

[AEF] 14:23:05.123Z INVOKE:START agent="assistant" prompt="What is 42 × 17?"
[AEF] 14:23:05.124Z ITER:START iteration=1/5
[AEF] 14:23:05.125Z LLM:START messages=3
[AEF] 14:23:05.830Z LLM:END tokens=142
[AEF] 14:23:05.831Z TOOL:START tool="calculator"
[AEF] 14:23:05.832Z TOOL:END tool="calculator" success=true
[AEF] 14:23:05.833Z ITER:END iteration=1 action="tool_call"
[AEF] 14:23:06.200Z LLM:END tokens=89
[AEF] 14:23:06.201Z ITER:END iteration=2 action="done"
[AEF] 14:23:06.202Z INVOKE:END agent="assistant" iterations=2 completed=true

You can customize the prefix:

new ConsoleObserver({ prefix: '[MyApp]' });

NoopObserver

Silently discards all events. This is what the agent uses internally when no observability option is provided:

import { NoopObserver } from '@agentic-eng/observability';

// These two are equivalent:
const agent1 = new Agent({ name: 'a', provider });
const agent2 = new Agent({ name: 'a', provider, observability: new NoopObserver() });

Event Types

The agent emits these structured events through the observer:

| Event | When | | --- | --- | | agent.invoke.start / end | Invoke lifecycle | | agent.invoke_stream.start / end | Stream lifecycle | | agent.iteration.start / end | Each reasoning iteration | | llm.call.start / end | Each LLM API call | | tool.call.start / end | Tool execution | | tool.schema.inject | Full schema injected for a tool | | tool.not_found | LLM requested unknown tool | | memory.store | Knowledge persisted | | agent.error | Any error during execution |

Building a Custom Observer

Need OTEL, Datadog, or a custom logging backend? Implement the ObservabilityProvider interface from @agentic-eng/provider:

import type { ObservabilityProvider, AgentEvent } from '@agentic-eng/provider';

class OtelObserver implements ObservabilityProvider {
  emit(event: AgentEvent): void {
    const span = tracer.startSpan(event.type);
    span.setAttributes(event.data ?? {});
    span.end();
  }
}

// Use it the same way
const agent = new Agent({
  name: 'assistant',
  provider: myProvider,
  observability: new OtelObserver(),
});

How It Fits Together

@agentic-eng/core (types + errors)
    ↑
@agentic-eng/provider (interfaces: LlmProvider, MemoryProvider, ObservabilityProvider)
    ↑
@agentic-eng/tool (Tool interface + ToolRegistry)
@agentic-eng/memory (FlatFileMemory — implements MemoryProvider)
@agentic-eng/observability (ConsoleObserver — implements ObservabilityProvider)  ← you are here
    ↑
@agentic-eng/agent (Agent class — composes everything)

Feedback & Contact

Have questions, feedback, or ideas? We'd love to hear from you:

• GitHub Issues: easa-framework/easa
• Email: [email protected]
• LinkedIn: Lahiru Nimantha

License

MIT