AgentCore

AgentCore is a lightweight local AI-agent execution runtime written in C17. It provides the validated tool-dispatch layer that an LLM or other controller can use later, without embedding a model provider, network client, or shell.

The first release accepts a structured JSON tool call, validates it, locates a registered tool, executes it, and returns one compact JSON result. Failed calls do not terminate the runtime.

Current capabilities

• Extensible tool definition and owned dynamic registry
• Strict JSON parsing with yyjson, duplicate-field checks, and bounded nesting
• Structured success and error results with monotonic execution timing
• Per-instance logging to stderr with configurable levels
• Injectable allocator abstraction used by AgentCore and yyjson
• Built-in echo and conservative read_file tools
• Single-call and JSONL batch CLI modes
• Linux and macOS CI with GCC, Clang, strict warnings, and AddressSanitizer

The library is split into agent, runtime, JSON, result, registry, tool, allocator, error, and logging modules. The agent owns the runtime and registry; the registry owns successfully registered tools; each parsed call owns its yyjson document; and serialized output is explicitly released through the originating agent or runtime. See docs/architecture.md for the complete lifecycle and ownership model.

Security model

AgentCore treats every tool call and argument as untrusted. This phase has no shell execution, writes, plugin loading, network access, or LLM connection. JSON input is limited to 1 MiB and 64 container levels. read_file is rooted at the process working directory captured when the agent is created, accepts only relative paths, rejects .. and every symlink component, reads regular files only, validates UTF-8, and enforces both request and configured size limits.

This is a conservative application boundary, not an OS sandbox. A process with hostile code running in the same address space can bypass it, and filesystem policy should eventually be reinforced with process isolation.

Build and test

Requirements are CMake 3.20 or newer, a C17 compiler, Git, and POSIX APIs. CMake fetches pinned yyjson and Unity releases during the first configuration.

cmake -S . -B build \
  -DCMAKE_BUILD_TYPE=Debug \
  -DAGENTCORE_BUILD_TESTS=ON
cmake --build build
ctest --test-dir build --output-on-failure

Available CMake options:

Option	Default	Purpose
AGENTCORE_BUILD_TESTS	ON	Build and register the Unity tests
AGENTCORE_ENABLE_ASAN	OFF	Enable AddressSanitizer
AGENTCORE_ENABLE_UBSAN	OFF	Enable UndefinedBehaviorSanitizer
AGENTCORE_WARNINGS_AS_ERRORS	OFF	Promote AgentCore warnings to errors

Example sanitizer build:

cmake -S . -B build-asan \
  -DCMAKE_BUILD_TYPE=Debug \
  -DAGENTCORE_ENABLE_ASAN=ON \
  -DAGENTCORE_WARNINGS_AS_ERRORS=ON
cmake --build build-asan
ctest --test-dir build-asan --output-on-failure

CLI

./build/agentcore --help
./build/agentcore --version
./build/agentcore tools
./build/agentcore execute \
  '{"id":"call_001","tool":"echo","arguments":{"message":"hello"}}'
./build/agentcore run examples/tool_calls.jsonl

Successful output is compact JSON on stdout; logs go to stderr:

{"id":"call_001","success":true,"tool":"echo","result":{"message":"hello"},"error":null,"duration_ms":0.011}

A malformed request also returns a complete JSON envelope:

{"id":null,"success":false,"tool":null,"result":null,"error":{"code":"JSON_PARSE","message":"unexpected end of data","details":{}},"duration_ms":0.01}

execute exits with status 1 when the call returns success:false. run processes every line and exits 1 after completion if any call failed. Usage, input-file, output, or unrecoverable runtime failures exit 2.

Set logging verbosity with AGENTCORE_LOG_LEVEL=trace, debug, info, warn, or error:

AGENTCORE_LOG_LEVEL=debug ./build/agentcore run examples/tool_calls.jsonl

Current limitations

• Tools are compiled in; there is no plugin ABI or dynamic loading.
• The registry uses a linear dynamic array.
• Argument schemas are descriptive strings; each tool performs its own strict validation rather than using a general JSON Schema engine.
• Execution is synchronous and in-process, with no timeout or cancellation.
• The filesystem root is the startup working directory, not an OS sandbox.
• There is no model provider, planning loop, approval UI, or execution history.

Roadmap

1. HTTP-based LLM provider interface
2. OpenAI-compatible API support
3. LM Studio and Ollama integration
4. Command-execution tool with allowlists
5. Write-file and patch tools
6. Git-diff inspection
7. User approval gates
8. Timeouts and process isolation
9. Persistent execution history
10. Agent planning loop

License

AgentCore is available under the MIT License.