@emberai/agent-node
Advanced tools
[](https://www.npmjs.com/package/@emberai/agent-node) [](https://github.com/EmberAGI/arbitrum-vibekit/blob/main/LICENSE
Agent Node is a complete implementation of the A2A (Agent-to-Agent) protocol with integrated AI capabilities, workflow orchestration, blockchain wallet support, X402 payment protocol for agent commerce, and EIP-8004 compliant on-chain registration for decentralized agent identity. Create intelligent agents that understand natural language, execute complex DeFi strategies, communicate with other agents, and monetize their services autonomously.
Agent Node provides a complete framework for building autonomous AI agents with the following core capabilities:
Agent Node uses a file-based configuration workspace:
config-workspace/
├── agent.md # Base agent + model config
├── agent.manifest.json # Skill/server selection
├── skills/ # Modular skill definitions
│ ├── general-assistant.md
│ └── ember-onchain-actions.md
├── workflows/ # Custom workflow implementations
│ └── sample-package/
│ ├── src/
│ │ └── index.ts
│ └── package.json
│ └── simple-script/
│ └── hello.js
│ └── utils/ # Workflow utility functions
├── mcp.json # MCP server registry
├── workflow.json # Workflow registry
└── README.md # Config workspace documentation
The configuration workspace contains several key files that define your agent's behavior.
agent.md)Base agent configuration including system prompt, model settings, A2A protocol card definition, and EIP-8004 registration details. See the generated config/agent.md file for the complete structure and examples.
skills/*.md)Modular skill definitions that compose your agent's capabilities. The init command creates two sample skills:
general-assistant.md - General assistant capabilitiesember-onchain-actions.md - On-chain DeFi operationsSee the generated files in config/skills/ for complete examples and structure.
agent.manifest.json)Skill composition and workflow selection settings. See the generated config/agent.manifest.json file for the complete structure.
mcp.json)MCP server registry for dynamic tool/resource access. See the generated config/mcp.json file for configuration examples.
workflow.json)Workflow plugin registry:
{
"workflows": [
{
"id": "sample-package-workflow",
"from": "./workflows/sample-package/src/index.ts",
"enabled": true,
"config": {
"mode": "default"
}
}
]
}
workflows/*.ts)Custom workflow implementations for multi-step operations that manage A2A Task lifecycles. The init command generates example workflows (sample-package/ and simple-script/). Refer to the generated files in config/workflows/ for working examples and see the Creating Workflows section for comprehensive documentation.
Before you begin, ensure you have:
[!NOTE] You can initialize Agent Node anywhere on your system. To take advantage of Vibekit's offered tools and capabilities, we recommend creating your agent node in the community agent directory.
npx -y @emberai/agent-node@latest init
[!NOTE] During initialization, you'll be prompted with optional EIP-8004 registration configuration for on-chain agent identity. See On-Chain Agent Registration for details on these prompts.
This creates a config/ directory with:
agent.md - Base agent configuration including system prompt, model settings, A2A protocol card definition, and EIP-8004 registration detailsagent.manifest.json - Skill composition settingsskills/ - Directory for skill modules (includes general-assistant.md and ember-onchain-actions.md)workflows/ - Directory for custom workflow implementations (includes sample-package/ and simple-script/ examples)mcp.json - MCP server registryworkflow.json - Workflow plugin registryREADME.md - Config workspace documentationSmart-start chat mode (connects to running agent or starts new server):
npx -y @emberai/agent-node@latest
You can now build and execute any DeFi strategy through simple conversation with the Agent Node.
[!TIP] Ready to customize your agent? Once you have Agent Node running, customizing your agent is as simple as editing configuration files. Your
config/directory contains everything needed to define your agent's personality, capabilities, and behavior. See the Configuration section above to learn about agent configurations and modify necessary files.
Agent Node supports on-chain agent registration using the EIP-8004 standard, which provides a decentralized registry for AI agents.
To register your agent, you'll need:
Pinata Account: For IPFS file uploads
Environment Variables:
PINATA_JWT=your_pinata_jwt_token
PINATA_GATEWAY=your_pinata_gateway_url
Wallet with ETH: To pay for transaction fees on your chosen chain
1. Configuration During Init
When you run npx -y @emberai/agent-node@latest init, you'll be prompted with optional EIP-8004 registration configuration:
These settings are saved to your agent.md frontmatter in the erc8004 section.
2. Registering Your Agent
Once configured, register your agent on-chain:
npx -y @emberai/agent-node@latest register
Optionally override specific fields:
npx -y @emberai/agent-node@latest register \
--name "My Trading Agent" \
--description "Autonomous DeFi trading agent" \
--url "https://myagent.example.com" \
--version "1.0.0" \
--image "https://example.com/agent-image.png" \
--chain 11155111
Options:
--chain <chainId>: Target a specific chain (overrides --all)--all: Register on canonical + mirror chains (default: true)--force-new-upload: Force new IPFS upload (ignores cached URI from previous attempts)3. Updating Registration
To update your existing registration:
npx -y @emberai/agent-node@latest update-registry \
--agent-id 123 \
--description "Updated: Now supports GMX v2" \
--version "2.0.0"
[!NOTE] Only the wallet that originally registered the agent can update its registration. This command calls
setAgentUri(agentId, newIpfsUri)on the registry contract to update the agent's metadata.
Workflows enable building complex multi-step operations that can pause for user input, request authorization, emit structured data, and track progress throughout execution. They use JavaScript async generator functions for sophisticated DeFi automation. Agent Node supports both package-based workflows with their own dependencies and simple script workflows.
For more detailed documentation, see Workflows as Packages for package-based workflow system with dependency management and Workflow Creation Guide for a comprehensive workflow development guide.
yield for state updates, return for final resultinput-required) or authorization (auth-required)type: 'status-update'type: 'artifact'submitted → working → input-required/auth-required → completedpackage.jsonAgent Node supports two types of workflows:
package.json and dependenciesStep 1: Create Directory Structure
mkdir -p config/workflows/my-workflow/src
cd config/workflows/my-workflow
Step 2: Create package.json
{
"name": "my-workflow",
"version": "1.0.0",
"type": "module",
"main": "src/index.ts",
"dependencies": {
"zod": "^3.24.1"
}
}
Step 3: Install Dependencies
pnpm install
Step 4: Create Workflow Plugin
Create src/index.ts:
import {
z,
type WorkflowContext,
type WorkflowPlugin,
type WorkflowState,
} from '@emberai/agent-node/workflow';
const plugin: WorkflowPlugin = {
id: 'my-workflow',
name: 'My Workflow',
description: 'A workflow with its own dependencies',
version: '1.0.0',
inputSchema: z.object({
message: z.string(),
}),
async *execute(context: WorkflowContext): AsyncGenerator<WorkflowState, unknown, unknown> {
const { message } = context.parameters ?? { message: '' };
yield {
type: 'status-update',
message: 'Processing your request...',
};
// Simulate some work
await new Promise((resolve) => setTimeout(resolve, 1000));
return { success: true, message };
},
};
export default plugin;
Step 5: Register Your Workflow
Add your workflow to config/workflow.json:
{
"workflows": [
{
"id": "my-workflow",
"from": "./workflows/my-workflow/src/index.ts",
"enabled": true,
"config": {
"mode": "default"
}
}
]
}
Step 6: Test Your Workflow
npx -y @emberai/agent-node@latest doctor
npx -y @emberai/agent-node@latest run --dev
Step 1: Create config/workflows/simple-task/task.js:
const plugin = {
id: 'simple-task',
name: 'Simple Task',
description: 'A workflow without dependencies',
version: '1.0.0',
inputSchema: null,
async *execute(context) {
yield {
type: 'status-update',
message: 'Running simple task...',
};
return { success: true };
},
};
export default plugin;
Step 2: Register Your Workflow
Add your workflow to config/workflow.json:
{
"workflows": [
{
"id": "simple-task",
"from": "./workflows/simple-task/task.js",
"enabled": true,
"config": {
"mode": "default"
}
}
]
}
Step 3: Test Your Workflow
npx -y @emberai/agent-node@latest doctor
npx -y @emberai/agent-node@latest run --dev
Your workflow becomes available as dispatch_workflow_my_workflow and can be triggered through natural language conversation with your agent.
The Agent CLI provides essential commands for managing your agent throughout its lifecycle, with chat as the default interactive experience.
# Initialize agent configuration - Creates a new agent configuration workspace with sample files
npx -y @emberai/agent-node@latest init
# Smart-start chat (default) - Attach to running agent, else start local then attach
npx -y @emberai/agent-node@latest
# Run agent in development mode - Starts your agent with hot reload for development
npx -y @emberai/agent-node@latest run --dev
# Validate configuration - Checks your configuration for errors and missing references
npx -y @emberai/agent-node@latest doctor
# View composed configuration - Shows your composed agent configuration in readable format
npx -y @emberai/agent-node@latest print-config
# Create deployment bundle - Creates a production-ready deployment package
npx -y @emberai/agent-node@latest bundle
# Register agent on-chain - Register your agent using EIP-8004 standard (requires PINATA_JWT)
npx -y @emberai/agent-node@latest register
# Update agent registry - Update existing on-chain registration
npx -y @emberai/agent-node@latest update-registry --agent-id 123
Chat supports smart-start behavior and flexible logging configurations:
# Smart-start (default): attach to running agent, else start local then attach
npx -y @emberai/agent-node@latest
# Client-only chat to a specific URL (never starts a server)
npx -y @emberai/agent-node@latest chat --url http://127.0.0.1:3000
# Start the server and then attach chat
npx -y @emberai/agent-node@latest run --attach
LOG_LEVEL=ERROR for console output to keep the stream clean--respect-log-level: Opt out; respect LOG_LEVEL from your environment--log-dir <dir>: Write daily JSONL logs to <dir> and suppress all console logs during chat
LOG_LEVELLogging Examples:
# Clean chat + file-only logs that honor .env LOG_LEVEL
npx -y @emberai/agent-node@latest --log-dir ./logs
# Client-only with file logs and environment log level
npx -y @emberai/agent-node@latest chat --url http://127.0.0.1:3000 --log-dir ./logs
# Respect environment log level in console (do not force ERROR)
npx -y @emberai/agent-node@latest --respect-log-level
# Start server then attach with file-only logs
npx -y @emberai/agent-node@latest run --attach --log-dir ./logs
MIT © EmberAGI
FAQs
[](https://www.npmjs.com/package/@emberai/agent-node) [](https://github.com/EmberAGI/arbitrum-vibekit/blob/main/LICENSE
We found that @emberai/agent-node demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Multiple high-impact npm maintainers confirm they have been targeted in the same social engineering campaign that compromised Axios.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.