dart_agent_core: Instructions file for Codex

AGENTS.md

This file provides guidance to Qoder (qoder.com) when working with code in this repository.

dart_agent_core is a mobile-first / local-first Dart library that implements a full agentic loop (tool use, streaming, state persistence, skills, sub-agents, planning, context compression, loop detection) plus an agent-evaluation subsystem. It targets Flutter/Dart apps with no Python or Node.js backend, and supports all 6 platforms including Web.

Common Commands

dart pub get                      # install dependencies

dart analyze .                    # static analysis (whole package, matches pana/CI)
dart format .                     # format; pana fails the score if anything is unformatted

dart test                         # run all tests
dart test test/planner_test.dart  # run a single test file
dart test -n "substring"          # run tests whose name matches

# Regenerate mockito mocks (*.mocks.dart) after changing mocked classes
dart run build_runner build --delete-conflicting-outputs

# Pub-score / platform-tag review (web support, lints, formatting)
pana --no-warning .

Running examples and the eval demo (require provider credentials via env vars):

export OPENAI_API_KEY=sk-...
dart run example/simple_agent_example.dart

# Eval harness demo: --suite calculator|card_agent|pkm_agent|all, --mode live|record|replay
export OPENAI_BASE_URL=https://...
dart run example/eval_demo/main.dart --suite all --concurrency 4 --mode live

# Transcript viewer CLI (reads eval traces)
dart run bin/transcripts.dart

Two Public Libraries

The package exposes two separate entry points — keep them decoupled:

• lib/dart_agent_core.dart — the agent runtime (clients, agent, tools, skills, state).
• lib/eval.dart — the evaluation subsystem (tasks, graders, suites, record/replay, metrics, reporting). It is intentionally a separate import so apps that don't run evals don't pay the import cost. Do not pull eval primitives into the main library.