europacore

The agent and harness core for building agent-based applications. It includes:

• AgentHarness: a multi-turn, tool-calling loop with:
  • guardrails
  • checkpoint/resume and human-in-the-loop approval
  • streaming
  • provider-agnostic retry
  • context compaction
  • sub-agent delegation
  • opt-in failure-spend governance (failure_spend_governance=True): a fan-out cap, a circuit breaker for identically failing calls, and a failure budget that steers a failing run to answer early (failure_arm_after_distinct_calls=2 arms it only once two different calls have failed, for tools that report ordinary misses as errors)
• SingleShotAgent: one prompt in, one schema-validated output, in a single forced LLM call.
• ToolAgent: the base class for the tools the harness dispatches.
• Built-in tools for planning, skills and delegation, each enabled by a flag. enable_planning=True registers todo_write and, by default, nudges the model to plan before substantial work; planning_mode="auto" keeps the tool and drops the nudge, so a one-line question costs no extra round-trip.
• An LLM layer: a Chat-Completions-shaped LLM contract with Amazon Bedrock (Claude), Anthropic API and OpenAI (Responses API) providers, plus a (name, version) prompt registry.
• Optional durable state and runtimes:
  • Postgres checkpointer and run journal
  • a Temporal-backed autonomous multi-agent runtime
  • sandbox providers (local subprocess, AWS Lambda MicroVMs)

Moving code from the library's predecessor? See docs/migration.md.

Install

Python 3.11+. The core has few dependencies; everything else is an extra, imported only when you use it:

pip install --pre europacore                              # core only (--pre: the 0.4 releases are alphas)
pip install --pre 'europacore[server,bedrock,postgres]'   # the server, Claude on Bedrock, Postgres state
europacore doctor --model claude-haiku-4-5                # what is installed and configured, and how to fix what is not

docs/install.md lists every extra, what europacore doctor checks, and the providers' environment variables.

Quickstart

Try it

One command serves the showcase offline, with no credentials: an assistant that plans, calls tools and asks before it saves a note, the Europa Bistro's table-booking flow, a refunds agent whose tool is a flow with an approval gate, and the flow designer with both flows in it:

pip install --pre 'europacore[server,graph]'
europacore demo                          # --repo DIR adds a sample repository and a coding agent that fixes it
npx @markmo/europacore-cli               # the terminal client (Node 22); or open the chat link the demo printed

The chat page at the server's address is europacoreui's session UI (europacoreui is the full product app) around this server; the terminal client is ec. europacore demo --model claude-haiku-4-5 runs the same agents live.

A new project

europacore init makes an agent project that passes its tests and serves offline before any credentials are set:

europacore init my-agents            # --model claude-haiku-4-5 to start on a live model
cd my-agents && pip install -e '.[dev]'
pytest                               # a scripted model plays the turns
npx @markmo/europacore-cli --spawn my_agents.agents:registry   # serve it and chat with it in the terminal

It writes:

• an agent registry (my_agents/agents.py), built with the option groups;
• its tools, one of which waits for the user's approval;
• offline tests with an eval set (evals/smoke.json);
• .env.example and a Dockerfile;
• a pyproject.toml that depends on europacore[server], plus the extra the model's provider needs.

The default model, demo, is an offline stand-in (europacore.testing.DemoLLM) that plans and calls the tools when asked to. Set EUROPACORE_MODEL to go live, and check it with europacore doctor.

In code

An agent that runs offline on a core-only install (examples/minimal_agent.py):

from europacore.agents import AgentHarness, function_tool
from europacore.testing import ScriptedLLM, text, tool_call

@function_tool
def add(a: float, b: float) -> float:
    """Add two numbers."""
    return a + b

llm = ScriptedLLM([tool_call("add", {"a": 2, "b": 40}), text("2 + 40 = 42")])   # plays the model
agent = AgentHarness(llm, tools=[add], system_prompt="You are a careful calculator.")
print(agent(question="What is 2 + 40?").text)

To go live, pass a real model instead of ScriptedLLM: create_model("claude-haiku-4-5") (europacore.llm) runs Claude on Bedrock, create_model("anthropic/claude-opus-5-5") on the Anthropic API, and create_model("gpt-6-luna") on OpenAI.

In a notebook

The same API, a step at a time: europacore notebook opens four notebooks (a first agent, durable state and approval, flows, evals) in euporie, a Jupyter client that runs in the terminal. They run offline, and your edits are kept:

pip install --pre 'europacore[notebooks,graph]'
europacore notebook                  # or `europacore notebook 02` for one; --list lists them

The guide

docs/guide goes from a first agent to agents that run unattended:

1. Building an agent: tools, structured answers, option groups, models, hooks, prompt templates, results and stop hints, security defaults
2. Durable state: checkpoints and the run journal, approvals, recovery, steering, inspecting runs, memory, tracing
3. The server: HTTP and SSE, editors over ACP, tool credentials
4. Flows: FlowScript, pauses, flows as tools, the designer
5. Coding agents: sandboxes, the coding agent and its monitors (a command or file watch whose output wakes the session), fleets, design checks, the autonomous runtime
6. Testing and evals: scripted models, cassettes, eval sets, europacore eval, pytest fixtures

europacore in pictures tours it all with screenshots: the coding agent, the ec terminal client, the web session UI, the flow designer and fleets.

What is in it

The examples run offline: minimal_agent.py, delegation_agent.py, mcp_agent.py, memory_agent.py, artifact_agent.py, monitor_agent.py, browser_agent.py (on a real browser), credentialed_tool.py, eval_in_ci, the server registries, flows and the coding agent. kubernetes deploys the server as two replicas on Postgres.

Reference

• api.md: every public name with its signature; anything not listed there is internal. deprecations.md says what a release may change.
• constructor.md: every AgentHarness argument, its default and its group.
• events.md: every event a run emits.
• settings.md: every EUROPACORE_* variable; europacore config shows their values.
• server-api.md and server-settings.md: the HTTP protocol, and running a server.
• threat-model.md: each trust boundary, its control and its test.
• llms.txt: this documentation's map, for coding agents.

Development

poetry install --all-extras
make check     # the suite, mypy, ruff and the design checks against main

docs/development.md has the other commands, and how to request the full CI gates.