Skip to main content
Agentica exposes utilities that listen to and log all agent and agentic function invocations and interactions. This includes both chat histories in and out of the REPL, as well as outputs of code executino in the REPL. This is useful for debugging, monitoring, and understanding your agent’s behavior.

​
Listeners

Listeners enable you to observe and log agent and agentic function invocations, chat histories, and interactions. This includes both chat histories in and out of the REPL, as well as outputs of code execution in the REPL. In TypeScript, this takes the form of callbacks referred to as listeners; every time a text chunk is generated (a token in the case of the agent), this callback is triggered, sending the chunk along with the ID for which the generation is apart of. 
(iid: string, chunk: Chunk) => void
The parameters are:
  • iid: a unique invocation ID for the specific invocation/call
  • chunk: a Chunk object:
interface Chunk {
    role: 'user' | 'agent' | 'system';
    content: string;
    type?: string; // 'reasoning', 'output_text', 'code', 'usage', etc.
}
The type field allows consumers to handle different kinds of streamed content (e.g. distinguishing reasoning traces from output text). The TypeScript SDK allows users to provide a callback to
  • spawn in AgentSpawnConfig,
  • Agent.call in AgentCallConfig and
  • agentic in AgenticConfig
via the parameter listener.

​
Usage Chunks

By default, usage-reporting chunks (chunk.type === 'usage') are filtered out of the listener stream. To include them, set listenerIncludeUsage: true: 
// At spawn time (applies to all calls)
const agent = await spawn({
    premise: "...",
    listener: (iid, chunk) => console.log(chunk.content),
    listenerIncludeUsage: true,
});

// Or per-call
const result = await agent.call("...", {}, {
    listener: (iid, chunk) => console.log(chunk.content),
    listenerIncludeUsage: true,
});

​
Streaming