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

Implementation Notes

Implementation Notes explains the internals layer of MTPX with practical guidance for building inspectable, tool-using agents.

Im
Implementation Notes
Chapter 008ArchitectureInternalsIndex
01Orientation

Implementation Notes belongs to the architecture 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 implementation notes affects a real MTPX agent before you wire it into an application.

  • What implementation notes 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 / minimal pattern
from mtp import Agent
from mtp.providers import Groq

agent = Agent.MTPAgent(provider=Groq(), tools=tools)
print(agent.run("Implementation Notes: explain the next runtime step.", max_rounds=4))
03 / manual

Read the system

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

Documentation index ↗
01Why policy hooks were added

Why policy hooks were added now

Your MTP direction includes operational safety and practical adoption. A protocol that only routes tool calls but has no execution-policy layer is hard to ship in production.

Current behavior:

  • read_only tools: default allow
  • write tools: default allow
  • destructive tools: default ask (blocked until approval flow is added)

This is configurable via RiskPolicy.

02Why plan validation is stric

Why plan validation is strict

If a provider emits invalid plan graphs, runtime errors become hard to debug. We validate before execution to fail fast and clearly.

03Why tool control-flow except

Why tool control-flow exceptions were added

Complex tool ecosystems need explicit signals to control the loop:

  • RetryAgentRun: feed correction guidance back to the model and replan.
  • StopAgentRun: intentionally stop/pause for continuation or user intervention.

These signals now travel from tool handler -> runtime -> agent loop without being flattened into generic tool errors.

04Why async provider hooks wer

Why async provider hooks were added

Agent async APIs now support provider-native async paths (anext_action, afinalize). If a provider only has sync methods, MTP uses thread fallback automatically. This keeps compatibility while preventing async app blocking when async hooks are implemented.

05Why run continuation exists

Why run continuation exists

continue_run() and acontinue_run() enable pause/resume flows with preserved message/tool context. This is especially useful when a run intentionally pauses via StopAgentRun.

06Compatibility with your MTP

Compatibility with your MTP vision

Implemented now:

  • lazy loading support in runtime
  • batch execution semantics
  • plan format with dependencies
  • safety policy hook
  • multi-provider adapter set (Groq/OpenAI/OpenRouter/Gemini/Anthropic/SambaNova)
  • multi-provider adapter set (Groq/OpenAI/OpenRouter/Gemini/Anthropic/SambaNova/Cerebras/DeepSeek/Mistral/Cohere/TogetherAI/FireworksAI)
  • run continuation and pause semantics
  • structured input schema validation
  • output model/parser model refinement pipeline
  • dynamic tool updates (add_tool, set_tools)
  • session persistence (JsonSessionStore, PostgresSessionStore, MySQLSessionStore)

Still needed to reach full ecosystem/library maturity:

  • CLI scaffolding
  • deeper provider feature parity and capability matrix
  • docs site and benchmark suite

Related:

01

Read

Understand where Implementation Notes 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 docLocal Inference