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

MTP Protocol Spec (Draft v0.1.0)

MTP Protocol Spec explains the protocol layer of MTPX with practical guidance for building inspectable, tool-using agents.

MT
MTP Protocol Spec
Chapter 014Core runtimeProtocolIndex
01Orientation

MTP Protocol Spec belongs to the core runtime 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 mtp protocol spec affects a real MTPX agent before you wire it into an application.

  • What mtp protocol spec 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("MTP Protocol Spec: 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 ↗
01Scope

Scope

This draft defines the in-process protocol model used by mtp-python.

Positioning note:

  • This file describes protocol-layer contracts only.
  • SDK/framework layering and MCP interoperability strategy are documented in:
  • Project Direction
02Core entities

Core entities

ToolSpec

  • name: stable tool identifier (toolkit.action recommended)
  • description: model-facing description
  • input_schema: JSON schema-like object for tool args
  • tags: optional model/runtime grouping hints
  • risk_level: read_only | write | destructive
  • cost_hint: optional human-facing cost hint
  • side_effects: optional description of expected side effects
  • cache_ttl_seconds: optional cache hint for runtime reuse
03ToolCall

ToolCall

  • id: unique call identifier inside a plan
  • name: selected tool name
  • arguments: dict payload
  • depends_on: list of call IDs required before this call
  • reasoning: optional public decision summary, not private chain-of-thought
04ToolBatch

ToolBatch

  • mode: parallel or sequential
  • calls: list of ToolCall
05ExecutionPlan

ExecutionPlan

  • batches: ordered list of batches
  • metadata: provider/planner metadata
06ToolResult

ToolResult

  • call_id, tool_name, output
  • success, error
  • cached
  • approval: policy decision used (allow/ask/deny)
  • skipped: true when blocked by policy
  • created_at: timestamp for the result object
  • expires_at: cache expiry timestamp when TTL caching is active
  • images, videos, audios, files: optional multimodal tool outputs
07ToolOutput

ToolOutput

Tools may return ToolOutput when they need to separate normal content from multimodal outputs:

  • content: primary tool output
  • images, videos, audios, files: optional media/file payloads
08Envelope

Envelope

MessageEnvelope provides a lightweight versioned wrapper:

  • mtp_version
  • kind
  • payload
  • metadata
09Validation rules

Validation rules

validate_execution_plan(plan) enforces:

  1. no duplicate ToolCall.id
  2. every dependency references an existing call ID
  3. dependency graph is acyclic
  4. $ref arguments and depends_on entries only target calls available earlier in execution order
10Execution semantics

Execution semantics

  1. Validate plan.
  2. Execute batches in order.
  3. For sequential batches, execute calls in listed order.
  4. For parallel batches, execute all listed calls concurrently.
  5. Before execution, resolve argument references:
  • { "$ref": "<call_id>" } replaces value with prior result output.
  1. Enforce risk policy.
  2. Apply cache lookup/store if TTL configured.
11Non-goals in v0.1.0

Non-goals in v0.1.0

  • transport protocol definition (HTTP/stdio/ws)
  • cryptographic signing/auth
  • streaming partial tool result chunks
  • formal RFC process

Persistence note:

  • Session persistence is implemented at runtime level (session_store) and is intentionally separate from the protocol model.

Related:

01

Read

Understand where MTP Protocol Spec 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 docProviders