AbstractAgent — Documentation

Overview

What AbstractAgent Is

Agent workflows implemented as pure logic, runtime adapters, and thin API wrappers — cleanly separated for testability and reuse.

Three-Layer Architecture

AbstractAgent separates concerns into three clean layers, making each independently testable and replaceable.

✓ Logic — prompting and response parsing, runtime-agnostic (src/abstractagent/logic/)
✓ Adapters — logic → WorkflowSpec with durable EffectType.* steps (src/abstractagent/adapters/)
✓ Agents — thin API wrappers via BaseAgent + concrete agents (src/abstractagent/agents/)

Logic Layer
ReActLogic · CodeActLogic · MemActLogic

→

Adapter Layer
Logic → WorkflowSpec + Effects

→

Agent Layer
BaseAgent + ReactAgent, CodeActAgent, MemActAgent

Agent Patterns

Features

Three agent patterns, durable execution, and production controls.

ReAct

Reason + Act loop. The LLM observes, thinks, picks a tool, observes the result, and repeats until it has an answer. The classic agentic pattern.

think → act → observe tool calling iterative

CodeAct

The LLM writes Python code blocks to accomplish tasks. Code is extracted and executed in a sandboxed subprocess with configurable timeout.

code generation sandboxed exec verifier policy

MemAct

ReAct extended with durable session memory. The agent persists knowledge across runs using runtime memory spans and knowledge graph edges.

session memory knowledge graph cross-run

Durability

Durable Runs

Every agent iteration is checkpointed by AbstractRuntime. Runs survive process restarts. Resume mid-conversation or mid-tool-execution.

Safety

Tool Approval

Configurable ToolApprovalPolicy gates dangerous operations. Safe tools auto-execute; mutations pause for human approval before proceeding.

Control

Max Iterations

Agents enforce a configurable iteration limit (default 50). When reached, the agent concludes with its best answer rather than looping indefinitely.

Sandbox

Code Execution

CodeAct runs Python in a local subprocess sandbox with timeout. execute_python tool with configurable security boundaries.

Delegation

Agent Delegation

Agents can delegate subtasks to other agents via the built-in delegate_agent tool, enabling hierarchical multi-agent workflows.

Persistence

Ledger & Replay

All LLM calls, tool executions, and decisions are logged to the append-only ledger. Replay any agent run from history for debugging.

Quickstart

Getting Started

Create an agent in a few lines and run it against any provider.

1. Install

pip install abstractagent

2. Create a ReAct Agent

from abstractagent.agents.react import create_react_agent

agent = create_react_agent(
    provider="openai",
    model="gpt-4o-mini",
)

result = agent.run("What is the capital of France?")
print(result)

3. Create a CodeAct Agent

from abstractagent.agents.codeact import create_codeact_agent

agent = create_codeact_agent(
    provider="ollama",
    model="qwen3:4b",
)

result = agent.run("Write a function that computes fibonacci numbers, then compute fib(10).")
print(result)

4. Create a MemAct Agent (with persistent memory)

from abstractagent.agents.memact import create_memact_agent

agent = create_memact_agent(
    provider="anthropic",
    model="claude-haiku-4-5",
)

# Memory persists across runs in the same session
result = agent.run("My name is Alice and I work at Acme Corp.")
result = agent.run("Where do I work?")
print(result)  # Recalls from session memory

5. With Custom Tools

from abstractcore import tool
from abstractagent.agents.react import create_react_agent

@tool
def lookup_user(user_id: str) -> str:
    """Look up user details by ID."""
    return f"User {user_id}: Alice, Engineering"

agent = create_react_agent(
    provider="openai",
    model="gpt-4o-mini",
    tools=[lookup_user],
)

result = agent.run("Look up user #42 and summarize their info.")
print(result)

Reference

API Surface

Package structure, imports, and key components.

Package Exports

# Agent constructors
from abstractagent.agents.react import ReactAgent, create_react_agent
from abstractagent.agents.codeact import CodeActAgent, create_codeact_agent
from abstractagent.agents.memact import MemActAgent, create_memact_agent

# Base agent (for custom agents)
from abstractagent.agents.base import BaseAgent

# Runtime-agnostic logic (prompting + parsing)
from abstractagent.logic.react import ReActLogic
from abstractagent.logic.codeact import CodeActLogic
from abstractagent.logic.memact import MemActLogic

# Runtime workflow adapters
from abstractagent.adapters.react_runtime import create_react_workflow
from abstractagent.adapters.codeact_runtime import create_codeact_workflow
from abstractagent.adapters.memact_runtime import create_memact_workflow

Source Tree

Logic

ReActLogic

CodeActLogic

MemActLogic

builtins.py

Adapters

react_runtime.py

codeact_runtime.py

memact_runtime.py

Agents

ReactAgent

CodeActAgent

MemActAgent

BaseAgent

Tools

execute_python

self_improve

delegate_agent

ALL_TOOLS

Agent Patterns Comparison

Pattern	How It Works	Best For
ReAct	Think → select tool → observe result → repeat	General-purpose agentic tasks, information retrieval, multi-step reasoning
CodeAct	Generate Python code → execute in sandbox → observe output	Data analysis, computation, file manipulation, automation scripts
MemAct	ReAct + durable session memory & knowledge graph	Long-running assistants, cross-session context, personalization

Key Design Rules

✓ Logic is runtime-agnostic — no abstractruntime imports in logic/
✓ Adapters bridge logic to runtime — logic → WorkflowSpec with durable EffectType.* steps
✓ Agents are thin wrappers — BaseAgent handles lifecycle, persistence, ledger access
✓ MemAct is not top-level — import from abstractagent.agents.memact
✓ Max iterations default: 50 — agents conclude rather than loop forever
✓ Default tools = full set — only explicit allowlists restrict available tools