0
mtpx
multi tool protocol
pip install mtpx
docs / runtime / sdk

Event Stream Contract

Event Stream Contract explains the events layer of MTPX with practical guidance for building inspectable, tool-using agents.

Ev
Event Stream Contract
Chapter 006ObservabilityEventsIndex
01Orientation

Event Stream Contract belongs to the observability track. The page breaks the idea into responsibilities, implementation rules, failure modes, and the signals you should expose in a product UI.

Use this when

Use this when you need to understand how event stream contract affects a real MTPX agent before you wire it into an application.

  • What event stream contract owns in the runtime.
  • How it connects to planning, tool execution, events, providers, or storage.
  • What to log, test, and expose to users when this layer is active.
  • Common mistakes that make agent systems hard to inspect.
02 / syntax starter
for event in agent.run_events("Inspect the repo", max_rounds=5):
    if event["type"] in {"tool_started", "tool_finished", "run_completed"}:
        print(event)
03 / manual

Read the system

The complete source manual—syntax, examples, linked references, edge cases, and implementation notes.

Documentation index ↗
01Base fields

MTP exposes a provider-agnostic event stream through:

pythonagent.run_events(prompt, max_rounds=5, stream_final=True)

or:

pythonagent.print_response(prompt, stream=True, stream_events=True)

All providers map into the same event shape.

print_response(..., stream_events=True) now defaults to human-readable terminal formatting. Use event_format="json" to print raw JSON lines. Pretty logs use explicit level prefixes such as INFO |, DEBUG |, and ERROR |.

Event verbosity follows debug_mode:

  • debug_mode=False (normal): concise lifecycle logs (run_started, round_started, streamed text, completion/cancel/pause/retry, strict violations).
  • debug_mode=True (debug): full trace, including plans, batch starts, assistant tool-call messages, and tool start/end payloads.
  • Debug trace includes only top-level XML sections for separation of concerns (<tools>, <team_members>, <system_instructions>, <user_instructions>, <orchestration_instructions>), plus metrics blocks.

Base fields

Every event includes:

  • type: event kind
  • timestamp: ISO 8601 UTC timestamp
  • run_id: stable id for the run
  • sequence: monotonic event index within the run
  • Optional run context fields on run_started: user_id, session_id, metadata
  • Optional validation field on run_started: input_validation_error
02Event types

Event types

  • run_started
  • user_message
  • max_rounds
  • tools_available
  • tool_names
  • direct_tool_names
  • delegation_tool_names
  • system_instructions
  • user_instructions
  • autoresearch
  • research_instructions
  • orchestration_instructions
  • member_agents: list of {id, mode, delegation_tool, role, tools}
  • stream_tool_events
  • stream_tool_results
  • round_started
  • round
  • llm_response
  • round
  • stage: optional ("finalize" for final response generation)
  • provider
  • model
  • usage: optional {input_tokens, output_tokens, total_tokens, reasoning_tokens}
  • duration_seconds
  • has_plan
  • has_response
  • plan_received
  • round
  • batches: list of {mode, calls, call_ids}
  • strict_violations
  • round
  • violations: list of {call_id, tool_name, message}
  • assistant_tool_message
  • round
  • message: raw assistant tool call message
  • batch_started
  • round
  • batch_index
  • mode
  • call_ids
  • tool_started
  • round
  • batch_index
  • call_id
  • tool_name
  • arguments
  • depends_on
  • reasoning (optional concise rationale summary)
  • tool_finished
  • round
  • call_id
  • tool_name
  • success
  • cached
  • approval
  • output (present only when tool-result streaming is enabled)
  • error (present only when tool-result streaming is enabled)
  • reasoning (optional concise rationale summary)
  • text_chunk
  • chunk
  • source: direct | finalize_stream | finalize_fallback
  • run_completed
  • final_text
  • rounds
  • total_tool_calls
  • run_terminated
  • round
  • reason
  • tool_name
  • run_cancelled
  • round
  • run_failed
  • round
  • error_type
  • error
  • tool_retry_requested
  • round
  • tool_name
  • feedback
  • run_paused
  • round
  • reason
  • tool_name
03Why this is provider-agnosti

Why this is provider-agnostic

Providers only produce actions/plans and optional token streams. The Agent owns event emission, so frontend code can consume one stable event model regardless of provider.

Related:

01

Read

Understand where Event Stream Contract sits in the agent loop before adding abstractions.

02

Wire

Connect the smallest useful provider, registry, store, or event stream first.

03

Observe

Expose events, logs, results, and failure states while the runtime is still moving.

04

Harden

Add policy, tests, retries, and audit traces after the behavior is visible.

Next docGroq Integration Guide