Introduction

Custom agents let you automate domain-specific tasks—tokenomics generation, frontend scaffolding, on-chain data indexing—integrated seamlessly into CODI’s Planner + Agents pipeline. This page covers SDK usage, project setup, registration, and best practices.

1. Use Cases & Architecture

• Use Cases: Token economics scripts, UI boilerplate, on-chain monitoring, gas optimizers.

• Architecture Fit: Agents run as sandboxed workers, access MCP context, and publish results via A2A.

2. Agent SDK & Interfaces

• Core Interface:

  interface Agent {
    name: string;
    init(context: Context): Promise<void>;
    run(context: Context): Promise<Artifact[]>;
    report(results: Artifact[]): Promise<void>
  
  

• SDK Modules: @codi/agent-sdk exports AgentBase, Context, registerAgent() helper.

3. Project Structure & Boilerplate

# src/index.ts
import { AgentBase, Context } from '@codi/agent-sdk';

class MyAgent extends AgentBase {
  name = 'my-agent';
  async run(ctx: Context) {
    // implement your logic
    return [{ type: 'result', data: {...} }]

4. Registering with Planner

• Add plugin path in codi.toml:

  [plugins]
  paths = ['./my-codi-agent']

• Planner auto-loads and schedules your agent based on command or custom hooks.

5. Context Access & A2A

• MCP Access:

• A2A Messaging:

6. Testing & Debugging

• Unit Tests: Mock Context using SDK’s test harness.

• Logging: Use ctx.logger to emit structured logs viewable in the UI.

• Local Debug: Run node --inspect src/index.ts inside your plugin folder.

7. Best Practices

• Keep agents single-responsibility and idempotent.

• Limit resource use: respect CPU/memory quotas.

• Clean up MCP nodes on errors to avoid stale state.

• Document input/output schemas for interoperability.

Conclusion

Building custom agents unlocks CODI’s full extensibility. Follow this guide to scaffold your plugin, integrate with the Planner, and leverage MCP/A2A for robust, automated workflows tailored to your Solana development needs.