agentropic 0.1.0

A minimal, hackable agentic framework: LLM calls via litellm, @tool-decorated functions, and MCP server support.

agentropic

A small, hackable agentic framework in ~500 lines you fully own and can read top to bottom in an afternoon:

• LLM calls go through litellm, so you get every provider (OpenAI, Anthropic, Gemini, Ollama, Bedrock, 100+ more) for free.
• @tool decorator turns any python function into an LLM-callable tool with an auto-generated JSON schema (from type hints + docstring).
• MCP support — connect to any Model Context Protocol server (stdio or SSE) and its tools show up in your agent automatically, indistinguishable from local tools.
• Agent loop handles the call → tool-call → tool-result → call cycle for you, with memory, streaming, and a max-iteration safety valve.

Install (once published)

pip install agentropic

Quick start

import asyncio
from agentropic import Agent, tool

@tool()
def get_weather(city: str) -> str:
    """Get the current weather for a city."""
    return f"It's sunny in {city}."

async def main():
    agent = Agent(
        name="assistant",
        model="gpt-4o-mini",         # any litellm model string
        instructions="You are helpful and concise.",
        tools=[get_weather],
    )
    print(await agent.arun("What's the weather in Paris?"))

asyncio.run(main())

Sync usage: agent.run("...") (wraps arun in asyncio.run for you).

Using MCP servers

from agentropic import Agent
from agentropic.mcp import StdioServer

agent = Agent(
    name="fs-agent",
    model="gpt-4o-mini",
    mcp_servers=[
        StdioServer(command="npx", args=["-y", "@modelcontextprotocol/server-filesystem", "."]),
    ],
)
print(await agent.arun("List the files in the current directory."))

Requires the optional MCP dependency: pip install "agentropic[mcp]".

Architecture

src/agentropic/
├── __init__.py     # public API surface
├── agent.py         # the run loop: LLM <-> tools <-> memory
├── llm.py            # thin litellm wrapper (swap providers here)
├── tools.py           # @tool decorator, Tool, ToolRegistry, schema generation
├── memory.py           # in-memory conversation history (swap for your own store)
└── mcp/
    └── client.py        # MCP stdio/SSE client -> Tool adapter

Everything is a plain, editable python file — no hidden magic, no plugin registry you can't inspect. Read agent.py first; that's the whole loop.

Extending it

• Custom memory / persistence: implement .add(), .get(), .clear() matching Memory and pass memory=YourMemory() to Agent.
• Streaming with tool calls: astream() currently falls back to a non-streamed arun() when tools are registered — extend it if you need token-level streaming mid-tool-loop.
• Multi-agent handoff: compose multiple Agent instances and route between them yourself, or wrap one agent's arun as a tool for another.

Publishing your fork to PyPI

1. Pick a unique name and check it's free: pip index versions your-name or just search on https://pypi.org. Update name in pyproject.toml (and rename the src/agentropic folder if you want the import name to match).

2. Bump the version in pyproject.toml and src/agentropic/__init__.py (__version__).

3. Install build tooling:

   pip install build twine
   

4. Build:

   python -m build
   

   This produces dist/agentropic-0.1.0.tar.gz and dist/agentropic-0.1.0-py3-none-any.whl.

5. Test on TestPyPI first (highly recommended):

   python -m twine upload --repository testpypi dist/*
   pip install --index-url https://test.pypi.org/simple/ agentropic
   

   You'll need a free account at https://test.pypi.org and an API token (Account Settings → API tokens). Use __token__ as the username and the token (starting pypi-...) as the password, or store it in ~/.pypirc:

   [testpypi]
   username = __token__
   password = pypi-...your-token...
   

6. Publish for real once it installs and works:

   python -m twine upload dist/*
   

   (needs an API token from https://pypi.org/manage/account/ the same way).

7. Every future release: bump the version number, python -m build again (delete the old dist/ first), twine upload dist/*.

Running tests

pip install -e ".[dev]"
pytest

License

MIT — do whatever you want with it.