@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

npm install @build0.ai/agent-core
# or
pnpm add @build0.ai/agent-core

Quick Start

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

{
  "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

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

interface MyPluginConfig extends BasePluginConfig {
  API_KEY: string;
}

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

  async init(config: MyPluginConfig): Promise<void> {
    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

Classes

• Runner - Main workflow orchestration engine

Singletons

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

Types

• McpPlugin<TConfig> - 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