Skip to main content

AbstractAgent

Agent patterns (ReAct / CodeAct / MemAct) built on AbstractRuntime (durable execution) and AbstractCore (tools + LLM integration).

AbstractAgent is part of the AbstractFramework ecosystem:

Start here: docs/getting-started.md (then docs/README.md for the full index)

How it fits (high level)

flowchart LR
  Host[Your app / service] --> Agent[AbstractAgent<br/>ReAct / CodeAct / MemAct]
  Agent --> RT[AbstractRuntime<br/>WorkflowSpec + Effects]
  RT --> Core[AbstractCore<br/>LLM + tool-call normalization]
  RT --> Stores[RunStore + LedgerStore]
  Agent --> Tools[Tool callables<br/>(abstractcore common_tools + agent tools)]

Documentation

What you get

  • ReAct: tool-first Reason → Act → Observe loop
  • CodeAct: executes Python (tool calls; on prompted-tools models also fenced ```python``` blocks)
  • MemAct (experimental): memory-enhanced agent using runtime-owned Active Memory — distinct architecture, less production mileage; import from abstractagent.agents.memact (deliberately not top-level)
  • Durable runs: pause/resume via run_id + runtime stores
  • Tool control: explicit tool bundles + per-run allowlists (unresolvable grant names are recorded loudly, never dropped silently)
  • Loop hooks: listen/steer/capture on the running loop via LoopHooks (see docs/hooks.md); the flat on_step callback remains
  • Generation controls: temperature, seed, media policy, prompt-cache identity, streaming, Core thinking and speculation (MTP) are normalized before LLM calls and inherited by delegated children
  • Scheduled runs (ReAct): the schedule_run tool schedules work or a reminder for later in the same conversation, with at most the agent's tools (see docs/tools.md)
  • Public conversation (ReAct, opt-in): short public updates from the ordinary continuation, an action-bound explanation for approval requests and timed clarification questions (see docs/public-conversation.md)
  • Observability: durable ledger of LLM calls, tool calls, and waits

Where this lives in code (source of truth):

  • Agents: src/abstractagent/agents/*
  • Workflows/adapters: src/abstractagent/adapters/*_runtime.py
  • Prompting/parsing logic (runtime-agnostic): src/abstractagent/logic/*
  • Default tool bundle: src/abstractagent/tools/__init__.py

Requirements

  • Python >=3.10 (see pyproject.toml)

Installation

From source (development):

pip install -e .

With dev dependencies:

pip install -e ".[dev]"

From PyPI:

pip install abstractagent

Native Python hardware profile cascades are available for deployment manifests: abstractagent[apple] and abstractagent[gpu]. These delegate to the matching AbstractCore and AbstractRuntime profiles; AbstractAgent itself remains provider/runtime agnostic.

AbstractAgent 0.5.0 requires abstractcore[tools]>=2.30.0 and AbstractRuntime>=0.16.0 (the runtime release that carries a public action explanation into tool approval waits and enforces conversational ask_user question policies, on top of the SCHEDULE_RUN effect behind the ReAct schedule_run tool, the 50k-token history window that ReAct applies when a host sets _runtime.history_window_tokens, live token streaming, turn grounding, in-flight cancellation and speculation inheritance).

What's new in 0.5.0: opt-in public conversation updates for ReAct, an action-bound public explanation for approval requests, and timed clarification questions with a declared fallback. See docs/public-conversation.md and the changelog.

Note: the repository may be ahead of the latest published PyPI release. To verify what you installed:

python -c "import importlib.metadata as md; print(md.version('abstractagent'))"

Quick start (ReAct)

from abstractagent import create_react_agent

# provider/model resolve from your AbstractCore config defaults
# (`abstractcore --config`) when omitted; pass them explicitly to pin.
agent = create_react_agent(provider="ollama", model="qwen3:4b")
agent.start("List the files in the current directory")
state = agent.run_to_completion()
print(state.output["answer"])

Tip: these loops send the full transcript plus ~19 tool schemas every cycle — prefer a tool-capable model. On Ollama, raise the context window to the model's maximum available context or the server silently truncates from the oldest content first: per-call llm_kwargs={"num_ctx": <model max>} or server-side OLLAMA_CONTEXT_LENGTH=<model max> ollama serve. House rule: maximum available context unless you explicitly choose otherwise — a fixed lower number is a hidden ceiling (see docs/faq.md).

Persistence (resume across restarts)

By default, the factory helpers use an in-memory runtime store. For resume across process restarts, pass a persistent RunStore/LedgerStore (example below uses JSON files).

from abstractagent import create_react_agent
from abstractruntime.storage.json_files import JsonFileRunStore, JsonlLedgerStore

run_store = JsonFileRunStore(".runs")
ledger_store = JsonlLedgerStore(".runs")

agent = create_react_agent(run_store=run_store, ledger_store=ledger_store)
agent.start("Long running task")
agent.save_state("agent_state.json")

# ... later / after restart ...

agent2 = create_react_agent(run_store=run_store, ledger_store=ledger_store)
agent2.load_state("agent_state.json")
state = agent2.run_to_completion()
print(state.output["answer"])

More details: docs/persistence.md

CLI

This repository still installs a react-agent entrypoint, but it is deprecated and only prints a migration hint (see src/abstractagent/repl.py and pyproject.toml).

Interactive UX lives in AbstractCode.

License

MIT (see LICENSE).

Metadata

Release files for abstractagent 0.5.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for abstractagent 0.5.0
File Size Uploaded Provenance Actions
abstractagent-0.5.0.tar.gz 343.6 kB With provenance Details for abstractagent-0.5.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for abstractagent 0.5.0
File Interpreter ABI Platform Actions
abstractagent-0.5.0-py3-none-any.whl Python 3 none any Details for abstractagent-0.5.0-py3-none-any.whl

Total release size: 558.4 kB

Release files / abstractagent-0.5.0.tar.gz

Download URL abstractagent-0.5.0.tar.gz
Size 343.6 kB
Tags Source
SHA-256 checksum
How to use checksums
1bf5ffa34d99da1d4e58f1c75d49908731c7a1631b90c430f15ae6809d01147f
BLAKE2b-256 checksum
How to use checksums
86567011215c230c95bb0418a44520c041e613b6ccca0003b7e6dd0d5c691ac0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 2, 2026.

Transparency log

Release files / abstractagent-0.5.0-py3-none-any.whl

Download URL abstractagent-0.5.0-py3-none-any.whl
Size 214.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
fbcaf9bdd7e923c873fb69bdcf416abd638ce77c9394f9e6fb4e6bc6c389d762
BLAKE2b-256 checksum
How to use checksums
e5fad0d58d4e7fa1373230aebd62badfc243def08b2c8cd20413e9e7a4512623
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 2, 2026.

Transparency log

Security for abstractagent 0.5.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for abstractagent-0.5.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 2, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page