agent-def

agent-def

A standardized, portable definition format for collaborative AI agents.

Overview

agent-def provides TypeScript/Zod schemas for defining agent configurations that can be validated, serialized as YAML frontmatter (agent.md files), and deployed across environments.

Core schemas:

• AgentDefinition - Identity, model, tools, groups, and instructions
• AgentConfiguration - Extends definition with services and runtime metadata
• Group - Organizational units (teams, projects, clusters)

Identity: Agent, tool, and group IDs can be simple strings (e.g., backend-architect) or more complex structures ( e.g. DIDs (Decentralized Identifiers), etc).

Installation

npm install agent-def

Usage

import { AgentDefinitionSchema, AgentConfigurationSchema } from "agent-def";

// Parse an agent definition
const agentDef = AgentDefinitionSchema.parse({
  id: "backend-architect",
  name: "Backend System Architect",
  modelId: "openai/gpt-4",
  toolIds: ["filesystem", "database-analyzer"],
  groupIds: ["team:backend", "project:api-v2"],
  agentIds: ["database-specialist"],
  instructions: "You are a backend system architect...",
});

// Extend with deployment configuration
const agentConfig = AgentConfigurationSchema.parse({
  ...agentDef,
  services: [
    { type: "mcp", id: "filesystem", url: "http://localhost:3000/mcp/fs" },
    {
      type: "a2a",
      id: "database-specialist",
      url: "https://agents.example.com/db",
    },
  ],
  metadata: { environment: "production", region: "us-east-1" },
});

agent.md Format

Store definitions as markdown files with YAML frontmatter:

---
id: backend-architect
name: Backend System Architect
modelId: openai/gpt-4
toolIds: [filesystem, database-analyzer]
groupIds: [team:backend, project:api-v2]
agentIds: [database-specialist, security-auditor]
---

You are a backend system architect specializing in scalable API design.
Focus on RESTful patterns, microservice boundaries, and database optimization.

Development

# Build the library
npm run build

# Generate JSON Schema
npm run generate:schema

# Run tests
npm test

# Lint code
npm run lint

Future Direction

The goal is to eventually merge more definitions (e.g. ProjectNanda Agent Definitions, Agency definitions) into a unified spec. This consolidation will enable consistent agent definitions, discovery, sharing, and simplified tooling across the artinet.

Contributing

We welcome contributions from the community! Whether you want to:

• Enhance the agent definition standard with new capabilities
• Improve documentation and examples
• Fix bugs or add features
• Share your use cases and patterns

Please read our Contributing Guide to get started. All contributors are recognized and appreciated.

License

Apache-2.0

Links

• GitHub Repository
• Issue Tracker
• Contributing Guide