Skip to content

development.md

Latest commit

 

History

History
100 lines (73 loc) · 6.96 KB

development.md

File metadata and controls

100 lines (73 loc) · 6.96 KB
Raw

Develop OpenAgentCore

Set up a checkout, build a component and validate your changes. To use an installation, start with the getting started guide. Read the contributor rules before changing code.

For component responsibilities and execution flow, read Architecture.

Set up a checkout

Work from an isolated worktree so experiments and validation do not disturb another checkout. From an existing clone with an up-to-date main:

git worktree add ../openagentcore-change -b codex/my-change main
cd ../openagentcore-change

Install Go at the version in go.mod, Node 22.13 or newer, pnpm at the version in package.json, and Python 3.9 or newer. The complete gate runs on Linux and needs a dedicated PostgreSQL database, OpenSSL development libraries for the microsandbox helper, and a Playwright browser. Provider and Runtime builds have additional prerequisites in their component guides.

pnpm install --frozen-lockfile
python3 -m venv .venv
.venv/bin/python -m pip install -r services/core/tests/requirements.txt
.venv/bin/python - <<'PYTHON'
import json
import subprocess
import sys

pin = json.load(open("contracts/agents-api/upstream.json"))
subprocess.check_call([
    sys.executable, "-m", "pip", "install",
    "git+" + pin["repository"] + "@" + pin["commit"],
])
PYTHON
pnpm exec playwright install --with-deps chrome
export OAC_TEST_OFFICIAL_SDK_PYTHON="$PWD/.venv/bin/python"

Set OAC_TEST_DATABASE_URL privately to a dedicated PostgreSQL test database. Never point the test suite at an installation or product database. The test database rules list the required role permission.

For native package pin changes, follow the live acceptance rules.

Build and run components

From the repository root:

make build-core
make build-daemon

Core build outputs and output-directory settings are in Standalone Core builds. The daemon is written to ${OAC_DEV_HOME:-$HOME/.oac}/build/daemon/oac-daemon.

Use the service guide to run the Core migrator and server with a separate development database. The configuration appendix owns standalone process settings. For a complete operator installation, use the installation guide; building Core alone is a separate contributor workflow.

For frontend development, run pnpm dev:web using the fixture or Core connection in the Web package guide.

Repository map

Location Responsibility Read next
services/core/internal/api Public, administrator and machine HTTP boundaries API index
services/core/internal/store and services/core/internal/db Core persistence, transactions, queries and migrations Service guide
services/core/internal/execution Durable Turn dispatch and scheduling Runtime protocol
services/core/internal/engine Pure qualification of harness operations and placements Harness onboarding
internal/agentdaemon/proto Core–Runtime wire types and validators Runtime protocol
internal/runtimebootstrap Provider-to-Runtime startup input Runtime bootstrap
apps/daemon/internal/dispatch Runtime preparation, Executor reuse, Turn and cleanup ownership Harness lifecycle
apps/daemon/internal/agent Native harness adapters Native references
services/core/internal/sandbox Provider interfaces and managed compute lifecycle Provider onboarding
services/web Console login and the server-side management proxy Console server
apps/web and packages/agents-client Console UI and typed clients Web guide
deploy/install and scripts Distribution, installation and validation tools Maintainers
contracts/agents-api Pinned schema, semantic contracts and coverage ledger Coverage ledger

Choose an extension boundary

Use the protocol map to find the code and guide for a new Harness, Sandbox Provider, model provider, API operation or Runtime message. The guide owns registration, supported operations and the checks that qualify an implementation. For workspace capabilities such as Skills, Plugins, MCP and system packages, start with Environments.

Validate a change

Run checks for the affected boundary while developing. The repository required checks define completion, including make check and any changed native component's real acceptance.

Change Focused validation
Core handlers, persistence or clients make check-core
SQL queries make sqlc-generate, inspect generated files, then make check-sqlc
Handler annotations or API contract make openapi, inspect all three namespace schemas
Shared Runtime protocol make check-runtime-contract
Provider integration make check-sandbox-provider-contract and the provider's native checks
Claude SDK bridge and artifact make check-claude-sdk
Web UI and clients make check-web
Distribution or installer make check-distribution
Documentation make check-names; make check-distribution validates Markdown links and bundled docs

Fixture browser acceptance uses loopback ports 18092 and 4174. Select unused ports with AGENTS_FIXTURE_PORT and AGENTS_WEB_PORT when running parallel validation. Keep databases, ports and containers separate between validation workers. Compilation, fixture success and live model/provider acceptance establish different facts; report skipped or unavailable checks explicitly. Follow the independent blind review workflow after validation.

Change documentation

Find the owning source in the documentation ownership map and follow the documentation rules. Readers use the authored Markdown in the repository. Generated OpenAPI schemas and the Harness catalog have their own generators; see Contract and schema rules.

The distribution has an explicit documentation list in scripts/core-distribution-manifest.py. When you move a bundled file or change a heading, update its inbound links and run the distribution documentation checks.