Skip to content

Explanation

Understanding-oriented documentation. The why: what AIMU is, how its parts fit together, and what tradeoffs the design makes (and refuses to make).

Read these when you want to know why the API looks the way it does, not just how to use it.

  • Architecture: the load-bearing shape: BaseModelClient, Agent, Runner, how providers dispatch.
  • Design principles: what AIMU deliberately doesn't do, and why (the line that separates AIMU from LangChain / LangGraph / Strands / PydanticAI).
  • Agents vs workflows: Anthropic's taxonomy and when to pick which.
  • StreamChunk model: why one chunk type instead of three.
  • System message lifecycle: seeded before the first chat, then swapped in place mid-conversation; reset() clears history.
  • Tool integration: @tool vs MCP, dispatch order, when to pick which route.
  • A2A vs MCP: sharing whole agents over the wire vs sharing tools; why both are optional, adapter-shaped, and composable through Runner.
  • Async design: why aimu.aio is a submodule (not method suffixes or smart routing), why asyncio.TaskGroup, and why in-process providers wrap an existing sync client.

For task-oriented usage, see how-to guides. For the API surface, see reference.