AgentiPy

⚠️ Prototype — exploring the idea of a filesystem-first, durable agent framework built on pydantic-ai v2.

This is an experimental prototype for research and exploration. It is not production-ready. The API, architecture, and implementation are all subject to change as the ideas are validated and iterated on.

Inspired by Eve.dev — exploring how to replicate its filesystem-first developer experience in Python, entirely on open-source foundations with no vendor lock-in.

my-agent/
├── pyproject.toml
└── agent/
    ├── agent.py                # Model config
    ├── instructions.md         # System prompt
    ├── tools/
    │   └── get_weather.py      # Tool: filename = tool name
    ├── skills/
    │   └── be-concise.md       # On-demand procedures
    └── channels/               # Platform entrypoints

Philosophy

The filesystem IS the interface. A file's location determines its role. No registry to maintain — add a file, and the agent discovers it.

Path	What it defines
agent/instructions.md	Always-on system prompt
agent/agent.py	Runtime config (model, description)
agent/tools/get_weather.py	Tool named get_weather
agent/skills/	On-demand markdown procedures
agent/channels/	Platform entrypoints (HTTP, Slack, etc.)

Quick Start

# Install
pip install agentopy

# Scaffold a new agent
agentopy init my-agent

# Chat with it
cd my-agent && agentopy chat

# Or start the HTTP server
agentopy dev --no-ui

Demo: Weather Agent

cd demo-agent
agentopy chat --agent-dir agent

# Or HTTP server
agentopy dev --agent-dir agent --no-ui

HTTP API

POST /agentopy/v1/session                 — Start a session
GET  /agentopy/v1/session/<id>/stream     — NDJSON event stream
POST /agentopy/v1/session/<id>            — Continue a session
GET  /health                               — Health check

curl -X POST http://127.0.0.1:2000/agentopy/v1/session \
  -H 'content-type: application/json' \
  -d '{"message":"What is the weather in New York?"}'

Architecture

┌─────────────────────────────────────────────────────────┐
│                    CLI / HTTP Client                     │
└──────────────────────┬──────────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────────┐
│                     EveAgent                             │
│  ┌─────────────┐  ┌──────────────────┐  ┌────────────┐  │
│  │  Loader     │  │  pydantic-ai     │  │  Sessions  │  │
│  │  (discovers │──►  Agent wrapper   │──►  (in-mem   │  │
│  │   files)    │  │  (tool reg,      │  │   store)   │  │
│  │             │  │   streaming)     │  │            │  │
│  └─────────────┘  └──────────────────┘  └────────────┘  │
└──────────────────────┬──────────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────────┐
│                   pydantic-ai v2                         │
│  ┌──────────┐  ┌──────────┐  ┌──────────────────────┐   │
│  │ Agent    │  │ Tools    │  │ Capabilities          │   │
│  │ (loop,   │  │(typed fn)│  │ (Think, WebSearch, …) │   │
│  │  stream) │  │          │  │                       │   │
│  └──────────┘  └──────────┘  └──────────────────────┘   │
└─────────────────────────────────────────────────────────┘

Key Design Decisions

1. Filesystem-first discovery

No registries, no imports. loader.py walks agent/ and builds a config from file paths. A file at agent/tools/get_weather.py becomes tool get_weather.

2. Thin wrapper over pydantic-ai

AgentiPy leverages pydantic-ai's battle-tested Agent class, tool system, streaming, and model abstraction:

• Provider-agnostic: OpenAI, Anthropic, Gemini, DeepSeek, Ollama — everything pydantic-ai supports
• Type-safe tools: All tools get validated parameter schemas
• Streaming: Built-in run_stream(), run_stream_events(), and iter() support
• Capabilities: Plug in Thinking, WebSearch, MCP, etc. via YAML

3. API design

POST /agentopy/v1/session and GET /agentopy/v1/session/<id>/stream follow Eve.dev's NDJSON streaming protocol for familiarity.

4. Session management

In-memory session store with message history across turns. Pluggable — swap in SQLite/PostgreSQL for production.

Comparison

Feature	Eve.dev	AgentiPy	pydantic-ai alone
Language	TypeScript	Python	Python
Filesystem-first	✅	✅	❌ (code-only)
YAML agent specs	❌	✅ (via agent.yaml)	✅
Durable execution	✅ (Workflow SDK)	🔄 (via pydantic-ai caps)	✅ (Temporal, DBOS, Prefect, Restate)
Open source	✅	✅	✅
Vendor lock-in	❌ (Vercel ecosystem)	✅ none	✅ none
Provider-agnostic	✅ (AI SDK)	✅ (pydantic-ai)	✅
NDJSON streaming	✅	✅	✅
MCP support	✅	🔄 (via pydantic-ai)	✅
Capabilities system	❌	🔄 (leverages pydantic-ai)	✅
Platform	Intel Mac, Apple Silicon	Any (Python)	Any

✅ = built-in | 🔄 = via pydantic-ai | ❌ = not available

Writing Tools

Each tool is a Python file in agent/tools/. The filename (minus .py) becomes the tool name.

# agent/tools/get_weather.py
from datetime import datetime

description = "Get the current weather for a city."


async def execute(city: str, units: str = "fahrenheit") -> dict:
    """Return weather data for the given city."""
    return {
        "city": city,
        "temp": 72,
        "condition": "Sunny",
        "unit": "F"[0],
        "reported_at": datetime.now().isoformat(),
    }

The file must define:

• description (str): What the model sees for this tool
• execute() (sync/async): The tool function, with typed parameters

Writing Skills

Skills are markdown files in agent/skills/. They're appended to the system prompt.

# Be Concise

When asked for a skill, respond in exactly one sentence.
No greetings, no sign-offs, no explanations.

Configuration

agent/agent.py:

model = "openai:gpt-4o"
description = "A friendly weather assistant"

Or agent/agent.yaml:

model: anthropic:claude-sonnet-4-20250514
description: A friendly weather assistant
instructions: "You are a concise weather bot."

Roadmap

• Filesystem loader (tools, instructions, skills)
• pydantic-ai Agent integration
• Session management with message history
• HTTP server with NDJSON streaming
• CLI: init, dev, chat, run
• YAML agent config support
• Durable execution (Temporal, DBOS capabilities)
• On-demand skill loading (not always in context)
• Subagents (nested agent directories)
• MCP connections
• Human-in-the-loop tool approval
• Slack/Discord channels
• Persistent session store (SQLite)
• OpenTelemetry/Logfire instrumentation

License

MIT