README
¶
2ai
AI foundation for systems that need models, tools and agents.
English · Tiếng Việt · 2found
2ai is a Go library for building AI applications with shared provider contracts, a native agent loop and telemetry. It supplies the foundation used by 2agent / Soot and AgentRay. Your application owns configuration, credentials, permissions and durable state.
Start in a minute
Requires Go 1.25 or later. For private repository access, authenticate GitHub
and set GOPRIVATE=github.com/2found/* before downloading modules.
git clone https://github.com/2found/2ai.git
cd 2ai
go mod download
go run ./examples/scripted
Expected output: Hello from 2ai. The example runs the native agent with a
scripted provider; it needs no API key, external service or JavaScript runtime.
Read the complete example, then explore the public API:
go doc ./agentcore.Config
go doc ./ai.FallbackProvider
go doc ./telemetry.NewInMemory
To use 2ai in your own Go module:
go get github.com/2found/2ai@main
Go records a commit-derived version in go.mod. Commit go.mod and go.sum;
keep deployments pinned to that version. Import packages such as
github.com/2found/2ai/ai and github.com/2found/2ai/agentcore.
Choose the layer you need
| Package | Use it for | Reference |
|---|---|---|
ai, ai/protocol |
Transcripts, provider streaming, OAuth and retry/fallback | AI |
agentcore |
Compose agents, limits, policies and tool grants | AgentCore |
agentcore/engine |
Low-level native loop and event streams | Engine |
agentcore/host |
Checkpoints and reusable host utilities | go doc ./agentcore/host |
agentcore/plugins |
Goals, memory, todo, jobs, subagents and guards | Plugins |
telemetry, telemetry/export, telemetry/llm |
Span recording and settled model traces | Telemetry |
credential |
In-memory host vault and secret references | go doc ./credential |
sandbox |
Host-bound file, shell, HTTP and execution tools | go doc ./sandbox |
jsonjs |
Lossless JSON and shared value identity | go doc ./jsonjs |
testing/agentcore |
Native session fixtures for consumer tests | go doc ./testing/agentcore |
The foundation has no application server, product database or CLI. Use 2agent for Soot's workspace, conversations, schedules, packs and app.
Contracts that matter
- Providers preserve ordered content, thinking signatures, tool IDs and usage.
- AI owns bounded retry/fallback. Visible output, cancellation and host failures stop fallback; the host binds selection and accounting callbacks.
- AgentCore owns one model loop. The engine stays below application policy; plugins extend composition without creating another runtime.
- Hosts resolve credentials and grant tools. Installing a capability does not grant permission. A workspace directory does not provide OS isolation.
- Native checkpoints and live value identity have ownership rules. Read package documentation before copying state or handling events concurrently.
Configured native transports cover Codex, Claude Code, Antigravity, Devin and OpenAI-compatible endpoints, including Gemini. Support varies by provider; AI documentation is the contract, not a promise of support for every model in a provider catalog.
Versioned releases
A new VERSION pushed to main releases only after CI passes. Each tag publishes
Go-module source, matching documentation and a checksummed download index.
Release policy · Releases and downloads.
Pin a published v<version> in consumers; @main above remains a development path.
Develop and verify
go test -race ./...
go vet ./...
go run ./examples/scripted
Ordinary checks use recorded fixtures, scripted providers and local HTTP
servers. Install Node.js 22.15+ and Python 3 to exercise the optional sandbox
eval tests; the Go library itself has no JavaScript runtime dependency.
Live provider and Docker tests skip unless their prerequisites are
explicitly supplied. The suite covers failure, cancellation, permissions,
retry accounting and concurrency. No sibling checkout or local replace is
required. For coordinated development, use an uncommitted Go workspace.
For coding agents
Read AGENTS.md first. It gives ownership boundaries, verification
commands and credential rules. Read the nearest package README and its boundary
tests next; use go doc to inspect exported types. Keep runtime behavior in its
owning layer and workload knowledge in the consuming application's config,
skills or tools. Keep this README and the Vietnamese version
in sync when changing setup or supported behavior.
Origin and license
Extracted from AgentRay's shared AI packages. SOURCE.json records
the source commit, original file hashes and path mapping. credential,
sandbox, JSON primitives and test helpers accompany the three main packages
so consumers build independently. AgentRay application and analytics code remain
in their own repository.
MIT, with original notices preserved. Derived Pi, TypeBox, partial-json and Unicode components retain their own notices beside the code; Pi provenance records upstream source hashes.
A 2found project. From idea to company.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package agentcore is a reusable, product-agnostic agent runtime: the turn loop, tool calling, hooks, permissions, memory, and the Agent Definition.
|
Package agentcore is a reusable, product-agnostic agent runtime: the turn loop, tool calling, hooks, permissions, memory, and the Agent Definition. |
|
engine
Code generated by testdata/generate-format-patterns.ts; DO NOT EDIT.
|
Code generated by testdata/generate-format-patterns.ts; DO NOT EDIT. |
|
host
Package host supplies reusable policy and checkpoint utilities around the native engine.
|
Package host supplies reusable policy and checkpoint utilities around the native engine. |
|
plugins/advisor
Package advisor reviews completed work and, optionally, work in progress at turn boundaries.
|
Package advisor reviews completed work and, optionally, work in progress at turn boundaries. |
|
plugins/ask
Package ask contributes the `ask` tool: the agent poses a structured question to the human — a prompt plus labeled options, optionally multi-select — and the run parks until the answer arrives.
|
Package ask contributes the `ask` tool: the agent poses a structured question to the human — a prompt plus labeled options, optionally multi-select — and the run parks until the answer arrives. |
|
plugins/finishguard
Package finishguard installs verify-on-stop: a bounded second look before a normal finish is accepted.
|
Package finishguard installs verify-on-stop: a bounded second look before a normal finish is accepted. |
|
plugins/goal
Package goal installs the run-level completion contract: a goal-gated run may only stop when it says so.
|
Package goal installs the run-level completion contract: a goal-gated run may only stop when it says so. |
|
plugins/jobs
Package jobs lets a tool go asynchronous.
|
Package jobs lets a tool go asynchronous. |
|
plugins/memory
Package memory installs the working-memory store used for recall across runs, and the model-facing curation tools that let the agent revise what it remembered: `learn` captures a reusable lesson, `memory_edit` updates or retracts a stored entry by id.
|
Package memory installs the working-memory store used for recall across runs, and the model-facing curation tools that let the agent revise what it remembered: `learn` captures a reusable lesson, `memory_edit` updates or retracts a stored entry by id. |
|
plugins/preset
Package preset composes agentcore's default agent out of the plugin packages.
|
Package preset composes agentcore's default agent out of the plugin packages. |
|
plugins/repeatguard
Package repeatguard breaks a run out of a tool-call loop by TELLING the model it is in one.
|
Package repeatguard breaks a run out of a tool-call loop by TELLING the model it is in one. |
|
plugins/sessionquery
Package sessionquery gives an agent authorized retrieval over its own durable session log.
|
Package sessionquery gives an agent authorized retrieval over its own durable session log. |
|
plugins/spill
Package spill keeps an oversized tool result out of the model's context WITHOUT destroying it.
|
Package spill keeps an oversized tool result out of the model's context WITHOUT destroying it. |
|
plugins/subagent
Package subagent installs spawn_subagent: self-forking and cross-agent delegation under shared depth and budget caps.
|
Package subagent installs spawn_subagent: self-forking and cross-agent delegation under shared depth and budget caps. |
|
plugins/todo
Package todo contributes a live run plan: a checklist the model writes for itself and that the loop pins into every request.
|
Package todo contributes a live run plan: a checklist the model writes for itself and that the loop pins into every request. |
|
Package ai owns provider transports, native transcripts, stream events, OAuth/account pools and model catalogs.
|
Package ai owns provider transports, native transcripts, stream events, OAuth/account pools and model catalogs. |
|
protocol
Package protocol owns provider-neutral request, capability, session and error contracts shared by AI clients and agent plugins.
|
Package protocol owns provider-neutral request, capability, session and error contracts shared by AI clients and agent plugins. |
|
Package credential provides the small, in-memory host vault shared by AgentRay and consumers of agentcore.CredentialResolver.
|
Package credential provides the small, in-memory host vault shared by AgentRay and consumers of agentcore.CredentialResolver. |
|
examples
|
|
|
scripted
command
An offline model run through the same native runtime used by applications.
|
An offline model run through the same native runtime used by applications. |
|
Package jsonjs normalizes serialized JSON using JavaScript value semantics.
|
Package jsonjs normalizes serialized JSON using JavaScript value semantics. |
|
Package sandbox provides isolation backends and the tools that run inside them, implementing agentcore.Sandbox.
|
Package sandbox provides isolation backends and the tools that run inside them, implementing agentcore.Sandbox. |
|
Package telemetry ports Pi's explicit-parent, callback-scoped telemetry to Go.
|
Package telemetry ports Pi's explicit-parent, callback-scoped telemetry to Go. |
|
export
Package export delivers completed telemetry scopes to host-owned sinks.
|
Package export delivers completed telemetry scopes to host-owned sinks. |
|
llm
Package llm defines the export format for model-call telemetry.
|
Package llm defines the export format for model-call telemetry. |
|
testing
Package telemetrytest provides runner-independent conformance cases for Go telemetry adapters, ported from Pi's telemetry/testing entry point.
|
Package telemetrytest provides runner-independent conformance cases for Go telemetry adapters, ported from Pi's telemetry/testing entry point. |
|
testing
|
|
|
agentcore
Package agentcoretest contains reusable conformance checks for agentcore boundary implementations.
|
Package agentcoretest contains reusable conformance checks for agentcore boundary implementations. |