Ezop
Project

Documentation

API Reference

Full reference for every method in the Ezop Python SDK.

agent.init()agent.close()agent.emit()agent.span()

agent.init()

Registers the agent and its version with the Ezop platform, and returns an Agent instance.

ParameterTypeRequiredDescription
namestrYesAgent name. Together with owner, uniquely identifies the agent on the platform.
ownerstrYesTeam or user that owns the agent.
versionstrYesVersion string (e.g. "v1.2.0"). A new version is registered if it does not exist yet.
runtimestrYesRuntime or framework used (e.g. "langchain", "crew", "custom").
descriptionstrNoHuman-readable description of the agent.
default_permissionslist[str]NoPermissions granted to all versions of this agent by default.
permissionslist[str]NoPermissions granted to this specific version.
changelogstrNoDescription of what changed in this version.

agent.close()

Closes the current run and records its outcome.

>/_ close.py
python
agent.close(
    status="success",
    message=None,
    metadata={"user_id": "u-123"},
)
ParameterTypeRequiredDescription
statusstrYesFinal status of the run. One of "success", "failed", "partial", "canceled", "running".
messagestrNoHuman-readable message describing the outcome, e.g. a failure reason.
metadatadictNoAny arbitrary JSON-serialisable data you want to attach to the run (e.g. user context, request identifiers, feature flags).

agent.emit()

Emits an event on the current run. Events capture discrete steps within a run such as LLM calls, tool invocations, or retrieval operations.

>/_ emit.py
python
agent.emit(
    name="llm.call",
    category="llm",
    type="llm_response",
    subtype=None,
    span_id="span-123",
    input={"prompt": "hello"},
    output={"text": "hi"},
    metadata={"model": "claude"},
    error=None,
)
ParameterTypeRequiredDescription
namestrYesFree-form event name (e.g. "llm.call", "tool.invoke").
categorystrYesTop-level event category. One of: "agent", "llm", "tool", "reasoning", "system", "user", "memory", "cost", "error".
typestrNoSpecific action within the category. Examples by category — agent: "agent_run_started", "agent_run_completed", "agent_run_failed"; llm: "llm_request", "llm_response"; tool: "tool_call_started", "tool_call_completed", "tool_call_failed", "tool_retry"; reasoning: "reasoning_step", "reasoning_plan", "reasoning_reflection", "reasoning_decision", "reasoning_final"; memory: "memory_query", "memory_retrieval", "memory_write"; system: "span_started", "span_completed"; user: "user_input", "user_feedback"; cost: "cost_calculated"; error: "error_raised".
subtypestrNoOptional detail layer. Reasoning subtypes: "chain_of_thought", "react", "reflection", "self_consistency". Tool subtypes: "http", "database", "filesystem", "api". Error subtypes: "timeout", "rate_limit", "validation", "tool_error", "llm_error".
span_idstrNoLinks this event to a span. Auto-set when emitting inside a span context manager.
inputanyNoInput passed to this step.
outputanyNoOutput produced by this step.
metadatadictNoAny arbitrary JSON-serialisable data to attach to the event.
errorstrNoError message if the event failed.

Tip — LLM events

Always pass the model name and token counts inside metadata so Ezop can calculate cost automatically. Anthropic returns usage in its response — you can map it directly:

>/_ anthropic.py
python
response = anthropic.messages.create(model="claude-opus-4-5", ...)

agent.emit(
    name="llm.call",
    category="llm",
    metadata={
        "model": "claude-opus-4-5",
        "usage": {
            "input_tokens": response.usage.input_tokens,
            "output_tokens": response.usage.output_tokens,
        },
    },
)

Tip — Tool events

For tool events, include tool_name and error_flag in metadata:

>/_ tool.py
python
agent.emit(
    name="tool.call",
    category="tool",
    type="tool_call_completed",
    metadata={
        "tool_name": "web_search",
        "error_flag": False,
    },
)

agent.span()

Returns a context manager that tracks a scoped duration as a span record. On enter it creates the span with a start_time; on exit it updates the span with an end_time.

>/_ span.py
python
with agent.span("llm.call", metadata={"model": "claude"}) as s:
    result = llm.generate(prompt)
ParameterTypeRequiredDescription
namestrYesSpan name (e.g. "llm.call", "tool.invoke").
metadatadictNoAny arbitrary JSON-serialisable data to attach to the span.

Nested spans automatically propagate context — each child span records the enclosing span's id as its parent_id, enabling tree reconstruction:

model.prompt (id: A, parent_id: None)
└── tool.call (id: B, parent_id: A)
└── memory.read (id: C, parent_id: B)

Events emitted inside a span are automatically linked to that span via span_id.