sunagent

KO | EN

gitlite — search

#dotnet #android #awesome #shell #html #gemini #csharp #linux #git #ai-agent

(★ 9)

A modular, provider-independent AI Agent runtime built from scratch for experimenting with and evaluating modern AI Agent architectures.

File Explorer

ZIP Download

- - 001.md
  - 002.md
- - 001-agent-loop-qna.md
  - 002-agent-loop-qna.md
  - 003-multi-turn-conversation.md
  - 004-terminal-bench-integration.md
- - 001-coder-skill-and-skill-loading.md
- README.md
- - eval100-code-v11-deepseek-v4-0731.md
  - eval100-code-v6.md
  - eval100-code-v7.md
  - eval100-code-v8.md
  - eval100-code-v9-deepseek-v4-0731.md
- - 2026-08-18__19-34-37__baseline-v0__terminal-bench-2.json
  - 2026-08-18__19-45-39__baseline-v0__terminal-bench-2.json
  - 2026-08-20__19-24-01__meta-v3__terminal-bench-2.json
  - 2026-08-21__12-29-55__meta-v3__terminal-bench-2.json
  - 2026-08-22__18-33-43__meta-v5__terminal-bench-2.json
  - 2026-08-23__16-29-19__meta-v5__terminal-bench-2.json
  - 2026-08-25__08-50-33__meta-v6__terminal-bench-2.json
  - 2026-08-26__20-10-03__meta-v8__terminal-bench-2.json
  - 2026-08-30__09-16-19__meta-v10__terminal-bench-2.json
  - eval100-code-v11-deepseek-v4-0731__code-v11__dataset-eval100.json
  - eval100-code-v6-1__code-v6__dataset-eval100.json
  - eval100-code-v7__code-v7__dataset-eval100.json
  - eval100-code-v8__code-v8__dataset-eval100.json
  - eval100-code-v9-deepseek-v4-0731__code-v9__dataset-eval100.json
- - build_swe_dataset.py
  - dev-50-swe.json
  - eval-100.json
  - readme.md
  - select_swe_tasks.py
  - smoke-10.json
- - tb2_tasks_by_difficulty.json
- baseline-v0.yaml
- code-v1.yaml
- code-v10.yaml
- code-v11.yaml
- code-v2.yaml
- code-v4.yaml
- code-v6.yaml
- code-v7.yaml
- code-v8.yaml
- code-v9.yaml
- files-v1.yaml
- meta-v1.yaml
- meta-v10.yaml
- meta-v11.yaml
- meta-v12.yaml
- meta-v2.yaml
- meta-v3.yaml
- meta-v4.yaml
- meta-v5.yaml
- meta-v6.yaml
- meta-v7.yaml
- meta-v8.yaml
- meta-v9.yaml
- - config.json
  - job.log
  - lock.json
  - result.json
- - config.json
  - job.log
  - lock.json
  - result.json
- - config.json
  - job.log
  - lock.json
  - result.json
- - config.json
  - job.log
  - lock.json
  - result.json
- - config.json
  - job.log
  - lock.json
  - result.json
- - config.json
  - job.log
  - lock.json
  - result.json
- - config.json
  - job.log
  - lock.json
  - result.json
- - config.json
  - job.log
  - lock.json
  - result.json
- - config.json
  - job.log
  - lock.json
  - result.json
- - config.json
  - job.log
  - lock.json
  - result.json
- - config.json
  - job.log
  - lock.json
  - result.json
- - config.json
  - job.log
  - lock.json
  - result.json
- - config.json
  - job.log
  - lock.json
  - result.json
- - 001-agent-loop.md
  - 002-run-agent-trace.md
  - 003-run-terminal-bench.md
  - 004-user-facing-events-and-cli-renderer.md
  - 005-harness-manifest-and-lineage.md
  - 006-meta-tools.md
- README.md
- session_memory.md
- diagnose_llm.py
- diff_scenario.py
- e2e_meta_tools.sh
- run_with_image_gc.py
- tool_stats.py
- - __init__.py
  - evaluation.py
  - events.py
  - harness.py
  - lineage.py
  - trace.py
- - test_events.py
  - test_loop.py
  - test_memory.py
  - test_observations.py
  - test_tool_error_budget.py
  - test_verification.py
- - __init__.py
  - test_cli.py
- - __init__.py
  - test_swe_verifier_template.py
- - __init__.py
  - test_executors.py
  - test_guard.py
  - test_workspace.py
- - __init__.py
  - test_evaluation.py
  - test_harness.py
  - test_lineage.py
- - __init__.py
  - test_harbor_agent.py
- - test_code.py
  - test_edit_safety.py
  - test_files.py
  - test_patch.py
  - test_registry.py
  - test_search.py
  - test_shell.py
  - test_symbols.py
.env.example
.gitignore
LICENSE
pyproject.toml
README.md
run_agent.py
runtime.log
uv.lock

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

> A modular AI Agent runtime implementation built from scratch for understanding, experimenting, and extending modern AI Agent architectures.

SunAgent is an open-source project that explores the core components behind AI Agent systems.

Instead of treating agents as black-box applications, this project focuses on understanding and implementing the underlying runtime mechanisms:

- Agent Loop
- Tool Calling
- Context Management
- Memory
- Planning
- Execution Runtime
- Reliability Engineering
- Observability

## Why This Project?

Modern AI Agents are moving from short-lived interactions toward long-running autonomous workflows.

The main challenge is no longer only model capability, but also:

- How agents manage state
- How agents execute actions reliably
- How agents recover from failures
- How agents observe and update their environment
- How developers build trustworthy agent systems

This project aims to build a modular Agent Runtime from first principles, where each component can be understood, tested, and extended independently.

## Project Structure

### docs

Contains design documents, technical concepts, architecture explanations, and interview notes.

It explains the "why" behind the Agent Runtime design, including core concepts, implementation decisions, and engineering trade-offs.

### src

Contains the core modular implementation of the Agent Runtime.

Each component is designed as an independent and reusable module, such as agent loop, tool execution, memory management, and reliability mechanisms.

### labs

Contains runnable experiments and quick-start guides for validating modules implemented in `src`.

Each lab provides a simple way to execute and explore a specific capability of the Agent Runtime.

### harnesses

Contains declarative agent configuration files (YAML) used to define and run
agent setups without changing code. Each harness describes the prompt, enabled
tools, control limits (e.g. `max_iterations`), memory strategy, recovery
behavior, and verification settings. Harnesses can extend others via `parent`,
making it easy to iterate on variants (e.g. `baseline-v0`, `meta-v3`) for
experiments and evaluations.

### evaluation

Contains benchmark task definitions and the records produced by running the
agent harness against them. The `terminal_bench` subdirectory holds the task
set (e.g. `terminal-bench-2`), while `records` stores timestamped JSON result
files for each evaluation run, useful for comparing agent configurations over
time.

### tests

Contains unit tests and integration tests to verify the correctness and reliability of the runtime components.

## Quick Start

Requires Python 3.12+ and [uv](https://docs.astral.sh/uv/).

```bash
uv sync

```

Copy the environment variable template and fill in your configuration:

```bash
cp .env.example .env

```

Then run:

```bash
uv run python run_agent.py "List the files in the current directory"

```

If another project's virtual environment is active, use `uv run --active` or
activate this project's `.venv` first. The warning about `VIRTUAL_ENV` is from
uv and is separate from the agent runtime.

Harbor is a project dependency (the `eval` group). Run it through `uv run` so it
shares this project's `.venv` with `agent_runtime` and its dependencies:

```bash
uv run harbor run \
  -d terminal-bench/terminal-bench-2 \
  --agent agent_runtime.integrations.harbor:HarborAgent \
  -l 1 \
  --debug
```

`uv run` puts the project's `.venv` on `sys.path` (where `agent_runtime` is
installed editable), so no `PYTHONPATH` prefix is needed.

## RunTrace

The agent loop emits a provider-independent event stream for each run. Keep it
in memory for tests, or append it as JSONL:

```python
from agent_runtime.agent import RunTrace, run_turn

trace = RunTrace(run_id="run-001", output_path="runs/run-001.jsonl")
answer = run_turn("What's the weather in Singapore?", llm, tools, trace=trace)
```

The event model contains lifecycle, LLM, and tool events: `agent.start`,
`agent.end`, `agent.error`, `llm.start`, `llm.error`, `llm.end`, `tool.start`,
`tool.error`, and `tool.end`. Each JSONL record includes
`run_id`, `event_id`, `event_type`, `timestamp`, `iteration`, and `data`.
The default payload is intentionally compact: it records counts, names, IDs,
durations, statuses, and errors, but not full prompts, model text, arguments, or
tool results.

Use `trace.span(name, ...)` to record an operation with explicit start, error,
and end events. The end and error events include `duration_ms`; result metadata
can be added through the yielded metadata dictionary.

## Environment Variables

The project uses an OpenAI-compatible Chat Completions API:

```dotenv
LLM_API_KEY=your-api-key
LLM_BASE_URL=https://api.example.com/v1
MODEL_ID=your-model

```

Supports OpenAI as well as model providers offering compatible interfaces. Keep your actual API keys strictly in your local `.env` file and do not commit them to Git.

## Learning Roadmap

Independent experiments will be added progressively:

* Message history and context management
* Tool calling and parameter validation
* Error handling, retries, and timeouts
* Streaming output
* Multi-agent collaboration
* Memory and retrieval augmentation
* Task planning and state machines
* Observability, evaluation, and debugging
* External tool protocols such as MCP

Each experiment will maintain a minimal codebase, complete with runnable examples and tests.

## Project Philosophy

This project follows a simple principle:

> Understand agents by rebuilding the fundamental components from scratch.

By decomposing complex agent systems into independent modules, developers can:

- Learn how modern agents work internally
- Experiment with different architectures
- Reuse components like building blocks
- Build customized agent systems

## Who Is This For?

- Engineers learning AI Agent architecture
- Developers building custom agent systems
- Researchers exploring agent runtime design
- Anyone interested in reliable autonomous AI systems

## License

MIT

sunagent

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

Download README