Skip to main content

​
AgentLogger

A pluggable base class that powers listeners by defining the logging behaviour itself. Subclass this and implement the abstract methods to create a custom logger. Can be used as a context manager to set a contextual logger for the current scope. 
class AgentLogger(ABC):

    local_id: LogId | None
    parent_local_id: LogId | None

    @abstractmethod
    def on_spawn(self) -> None:
        ...

    @abstractmethod
    def on_call_enter(self, user_prompt: str, parent_local_id: LogId | None = None) -> None:
        ...

    @abstractmethod
    def on_call_exit(self, result: object) -> None:
        ...

    @abstractmethod
    async def on_chunk(self, chunk: Chunk) -> None:
        ...
Parameters
​
local_id
LogId | None
The local identifier for this logger instance.
​
parent_local_id
LogId | None
The local identifier of the parent logger, if any.

​
on_spawn

Called when an agent is spawned. Implementations should initialise any logging state needed for a new agent. 
def on_spawn(self) -> None:
    ...

​
on_call_enter

Called when an agent receives a prompt. 
def on_call_enter(self, user_prompt: str, parent_local_id: LogId | None = None) -> None:
    ...
Parameters
​
user_prompt
str
The task or prompt provided to the agent for this invocation.
​
parent_local_id
LogId | None
The local identifier of the parent invocation, if this is a nested call.

​
on_call_exit

Called when an agent returns a result. 
def on_call_exit(self, result: object) -> None:
    ...
Parameters
​
result
object
The result returned by the agent invocation.

​
on_chunk

Called when a streaming chunk is received. 
async def on_chunk(self, chunk: Chunk) -> None:
    ...
Parameters
​
chunk
Chunk
A single piece of streamed content from an agent invocation.

​
Chunk

A single piece of streamed content from an agent invocation. 
@dataclass
class Chunk:

    role: Role
    content: str
    type: str | None = None  # 'reasoning', 'output_text', 'code', etc.
Parameters
​
role
Role
The role of the message sender (‘agent’, ‘user’, or ‘system’).
​
content
str
The text content of the chunk.
​
type
str | None
The kind of streamed content:
  • ‘reasoning’ — internal reasoning / chain-of-thought
  • ‘output_text’ — final output text
  • ‘code’ — code being executed in the REPL
  • ‘usage’ — token usage statistics
  • ‘invocation_exit’ — signals the end of an invocation
  • None — untyped chunk