@build0.ai/agent-core

Core framework for Build0 autonomous coding agents. This package provides the workflow orchestration engine, plugin system, and utilities needed to build autonomous agents.

Installation

``bash
npm install @build0.ai/agent-core


or


pnpm add @build0.ai/agent-core
`

Quick Start

`typescript
import { Runner, credentialManager } from "@build0.ai/agent-core";
import { myPlugin } from "./plugins/my-plugin.js";

async function main() {
// Fetch credentials from remote API
const credentials = await credentialManager.fetchCredentials();

// Create runner and register plugins
const runner = new Runner();
await runner.registerPlugin(myPlugin, {
API_KEY: credentials.MY_API_KEY!,
});

// Run workflow
await runner.runWorkflow("./workflow.json");
}

main();
`

Features

- Declarative Workflows: Define agent behavior in JSON
- Type-Safe Plugin System: Build plugins with compile-time validation
- MCP Tools Integration: Tools are exposed via Model Context Protocol
- Claude Agent SDK: Leverages Claude for intelligent coding tasks
- Credential Management: Secure remote credential fetching and decryption
- Structured Logging: JSON-formatted logs for easy parsing

Workflow Format

`json
{
"steps": [
{
"id": "step_1",
"type": "tool",
"tool": "my_tool",
"args": {
"param": "value"
}
},
{
"id": "step_2",
"type": "ai_agent",
"args": {
"prompt": "Analyze the output: {{ step_1.output }}",
"working_dir": "./workspace"
}
}
]
}
`

Creating Plugins

`typescript
import { McpPlugin, BasePluginConfig, ToolDefinition } from "@build0.ai/agent-core";
import { z } from "zod";

interface MyPluginConfig extends BasePluginConfig {
API_KEY: string;
}

export const myPlugin: McpPlugin = {
name: "my_plugin",
config: {} as MyPluginConfig,

async init(config: MyPluginConfig): Promise {
if (!config.API_KEY) {
throw new Error("API_KEY is required");
}
this.config = config;
},

registerTools(): ToolDefinition[] {
return [
{
name: "my_tool",
description: "Does something useful",
zodSchema: z.object({
param: z.string().describe("A parameter"),
}),
},
];
},

async handleToolCall(name, args) {
if (name === "my_tool") {
// Implementation
return {
content: [{ type: "text", text: "Result" }],
};
}
throw new Error(Unknown tool: ${name});
},
};
`

Environment Variables

The framework uses these environment variables:

- BUILD0_AGENT_CREDENTIALS_URL - Remote credentials API endpoint
- BUILD0_AGENT_AUTH_TOKEN - Authentication token for credentials API
- BUILD0_AGENT_ENCRYPTION_KEY - AES-256 key for credential decryption (hex)
- BUILD0_TRIGGER_PAYLOAD - JSON payload from external triggers (auto-injected as {{ input }})
- ANTHROPIC_API_KEY - API key for Claude (required by Claude Agent SDK)

Exports

$3


- Runner - Main workflow orchestration engine

$3

- logger - Structured JSON logger
- credentialManager - Credential fetching service

$3

- McpPlugin - Plugin interface
- BasePluginConfig - Base plugin configuration
- ToolDefinition - Tool metadata with Zod schema
- Workflow - Workflow definition
- WorkflowStep - Single workflow step
- Credential - Credential structure
- AgentResult` - AI agent execution result
- Various log message types

License

MIT