agentix

A lightweight multi-agent framework built on top of pydantic-ai.

Documentation

Full documentation is in the docs/ directory. Start at docs/INDEX.md.

Install

From PyPI:

pip install ibhax-agentix
# or with the OpenAI provider used by the demo:
pip install ibhax-agentix[openai]

For local development:

pip install -e .
# or with the OpenAI provider used by the demo:
pip install -e '.[openai]'

Quick start

from pydantic import BaseModel
from agentix import AgentBuilder, AgentConfig, run

class Summary(BaseModel):
    text: str

cfg = AgentConfig.from_env("OPENROUTER_API_KEY", model="openai/gpt-4o-mini")

agent = (
    AgentBuilder("summariser", cfg, output_type=Summary)
    .system_prompt("Summarise the user's text in one sentence.")
    .build()
)

result = run(agent, "pydantic-ai is a Python framework for building production-grade LLM apps")
print(result.output.text)
print(f"({result.elapsed_ms:.0f} ms)")

Core concepts

AgentConfig

Holds provider + model config. Never hardcode API keys.

# From environment variable (recommended)
cfg = AgentConfig.from_env("OPENROUTER_API_KEY", model="minimax/minimax-m3", temperature=0.7)

# Or directly (e.g. in tests)
cfg = AgentConfig(api_key="sk-...", model="openai/gpt-4o")

AgentBuilder

Fluent builder that wraps pydantic-ai's Agent. Fully type-safe via generics.

agent = (
    AgentBuilder("my_agent", cfg, output_type=MySchema)
    .system_prompt("You are ...")
    .tool(my_python_function)       # plain callable → tool
    .sub_agent("other_agent")       # registered agent → tool (lazy lookup)
    .temperature(0.3)
    .max_tokens(512)
    .build()
)

AgentRegistry

Thread-safe global registry. build(register=True) handles it automatically.

from agentix import AgentRegistry

AgentRegistry.names()               # ["math_joker", "critic", ...]
AgentRegistry.get("math_joker")     # → Agent
AgentRegistry.clear()               # useful in tests

Pipeline

Chain agents sequentially. Each step's output becomes the next step's input (via str()).

from agentix import Pipeline

result = (
    Pipeline("draft → critique → polish")
    .step(drafter_agent)
    .step(critic_agent)
    .step(polisher_agent)
    .run("Write a haiku about distributed systems.")
)

Supply a custom adapter to control how output is forwarded:

pipeline.step(critic_agent, adapter=lambda out: f"Critique this: {out.text}")

run / run_async

from agentix import run, run_async

result = run(agent, "Hello")
print(result.output)       # typed output (your Pydantic model)
print(result.elapsed_ms)   # wall-clock time in ms

# Async
result = await run_async(agent, "Hello")

Persistent memory

agentix provides a persistent, tiered memory layer backed by ChromaDB. Four memory types are enabled by default:

• Short-term: recent conversation turns within the current session.
• Long-term: vector-retrieved relevant memories across sessions.
• State: structured key/value state for the session/user.
• Session: lightweight per-session metadata/summary.

To activate memory, provide a session_id when running:

from agentix import run, MemoryConfig

# All four memory types are on by default.
result = run(agent, "Hello again", session_id="session-123")

# Seed state memory at the start of a run.
result = run(agent, "How am I?", session_id="session-123", state={"mood": "happy"})

# Disable specific memory types during agent creation.
agent = (
    AgentBuilder(
        "my_agent",
        cfg,
        output_type=MySchema,
        memory=MemoryConfig(long_term=False, state=False),
    )
    .system_prompt("You are a helpful assistant.")
    .build()
)

# Or use the fluent method.
agent = (
    AgentBuilder("my_agent", cfg, output_type=MySchema)
    .with_memory(MemoryConfig(short_term=False, session=False))
    .build()
)

Environment variables

Examples that call an LLM or use web search expect API keys in a .env file in the project root. Copy the template and fill in your keys:

cp .env.example .env

Examples

• examples/single_agent.py — one agent with structured output.
• examples/multi_agent.py — orchestrator that delegates to sub-agents.
• examples/sequential_pipeline.py — chained agents with custom adapters.
• examples/parallel_agents.py — run multiple agents concurrently.
• examples/web_search_agent.py — agent with an Exa AI web-search tool.
• examples/agent_team.py — research → draft → edit pipeline.
• examples/agentix_demo.py — basic multi-agent builder, registry, and pipeline demo.
• examples/exa_memory_demo.py — research agent with web search and all four memory types.

Project layout

.
├── pyproject.toml
├── README.md
├── examples/
│   ├── single_agent.py
│   ├── multi_agent.py
│   ├── sequential_pipeline.py
│   ├── parallel_agents.py
│   ├── web_search_agent.py
│   ├── agent_team.py
│   ├── agentix_demo.py
│   └── exa_memory_demo.py
└── src/
    └── agentix/
        ├── __init__.py          # public API
        ├── py.typed             # typed package marker
        ├── builder/             # AgentBuilder
        ├── config/              # AgentConfig
        ├── exceptions/          # AgentixError hierarchy
        ├── memory/              # MemoryConfig / MemoryManager
        ├── pipeline/            # Pipeline
        ├── registry/            # AgentRegistry
        └── runner/              # run / run_async / RunResult

Author

• Albin Anthony — @IbhaX
• Email: albin.anthony.dev@gmail.com
• Website: https://ibhax.com