{"_id":"@ai-agent-schema/schema","name":"@ai-agent-schema/schema","dist-tags":{"latest":"0.4.0"},"versions":{"0.4.0":{"name":"@ai-agent-schema/schema","version":"0.4.0","description":"Standardized JSON schema and TypeScript SDK for defining AI agents and workflows with framework adapters","type":"module","main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"scripts":{"build":"tsup","dev":"tsup --watch","test":"vitest","test:ui":"vitest --ui","test:coverage":"vitest --coverage","lint":"eslint src tests --ext .ts","lint:fix":"eslint src tests --ext .ts --fix","format":"prettier --write \"src/**/*.ts\" \"tests/**/*.ts\"","format:check":"prettier --check \"src/**/*.ts\" \"tests/**/*.ts\"","typecheck":"tsc --noEmit","verify":"npm run build && npm run lint && npm run test -- --run","prepublishOnly":"npm run build"},"keywords":["ai","agent","schema","json-schema","zod","validation","typescript","llm","workflow","n8n","langchain","crewai","adapter","framework"],"author":{"name":"Shaun Ganley"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/shaunganley/ai-agent-schema.git"},"bugs":{"url":"https://github.com/shaunganley/ai-agent-schema/issues"},"homepage":"https://github.com/shaunganley/ai-agent-schema#readme","publishConfig":{"access":"public"},"devDependencies":{"@types/node":"^20.10.0","@typescript-eslint/eslint-plugin":"^6.13.0","@typescript-eslint/parser":"^6.13.0","@vitest/ui":"^1.0.4","eslint":"^8.54.0","eslint-config-prettier":"^9.0.0","eslint-plugin-prettier":"^5.0.1","prettier":"^3.1.0","tsup":"^8.0.1","typescript":"^5.3.2","vitest":"^1.0.4"},"dependencies":{"zod":"^3.22.4","zod-to-json-schema":"^3.22.3"},"_id":"@ai-agent-schema/schema@0.4.0","gitHead":"a3b0887557ca006ce55a0598777c00c8a60cc68c","_nodeVersion":"20.19.5","_npmVersion":"10.8.2","dist":{"integrity":"sha512-/G1aO6280OEtXQpNVxV0iMAGAJJxRgxhyB9EuTe1IKQcwTBzhqcL0NiybUhYOnOQSyp0tyu2R288NuVb1NxPJg==","shasum":"726d2bf36e7375f2249920efd4c9324197bfea81","tarball":"https://registry.npmjs.org/@ai-agent-schema/schema/-/schema-0.4.0.tgz","fileCount":9,"unpackedSize":357243,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCvB9XPhqfRem0HPh4SnGsd/iNf2fPbIp1lhKcS0381bQIgbalLqrGewTCSTsP+CjnlzXocW+Kd4KvBnVo1s0Vt4bY="}]},"_npmUser":{"name":"sganley27","email":"sganley27@gmail.com"},"directories":{},"maintainers":[{"name":"sganley27","email":"sganley27@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/schema_0.4.0_1760611951798_0.6278509507673382"},"_hasShrinkwrap":false}},"time":{"created":"2025-10-16T10:52:31.659Z","0.4.0":"2025-10-16T10:52:31.975Z","modified":"2025-10-16T10:52:32.325Z"},"maintainers":[{"name":"sganley27","email":"sganley27@gmail.com"}],"description":"Standardized JSON schema and TypeScript SDK for defining AI agents and workflows with framework adapters","homepage":"https://github.com/shaunganley/ai-agent-schema#readme","keywords":["ai","agent","schema","json-schema","zod","validation","typescript","llm","workflow","n8n","langchain","crewai","adapter","framework"],"repository":{"type":"git","url":"git+https://github.com/shaunganley/ai-agent-schema.git"},"author":{"name":"Shaun Ganley"},"bugs":{"url":"https://github.com/shaunganley/ai-agent-schema/issues"},"license":"MIT","readme":"# 🧠 AI Agent Schema\n\nA standardized JSON schema and TypeScript SDK for defining AI agents and their configurations, enabling interoperability between AI frameworks.\n\n[![npm version](https://badge.fury.io/js/@ai-agent-schema%2Fschema.svg)](https://www.npmjs.com/package/@ai-agent-schema/schema)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n## 🎯 Overview\n\nAI Agent Schema provides a **universal standard** for describing AI agents, their configuration, and how they connect in workflows. This enables seamless interoperability between different AI agent frameworks like n8n, LangChain, CrewAI, and Flowise.\n\n## ✨ Features\n\n- ✅ **Type-safe** TypeScript definitions\n- ✅ **Runtime validation** using Zod\n- ✅ **JSON Schema generation** for UI tools\n- ✅ **Workflow orchestration** - Connect agents in DAG-based workflows\n- ✅ **Lightweight** and tree-shakable\n- ✅ **Provider-agnostic** (OpenAI, Anthropic, Google, and more)\n- ✅ **Extensible** metadata and configuration\n- ✅ **Cycle detection** and topological sorting for workflows\n\n## 📦 Installation\n\n```bash\nnpm install @ai-agent-schema/schema\n```\n\n```bash\nyarn add @ai-agent-schema/schema\n```\n\n```bash\npnpm add @ai-agent-schema/schema\n```\n\n## 🚀 Quick Start\n\n### Basic Usage\n\n```typescript\nimport { validateAgentConfig, type AgentConfig } from '@ai-agent-schema/schema';\n\n// Define your agent configuration\nconst agentConfig = {\n  id: 'agent1',\n  name: 'Research Agent',\n  provider: 'openai',\n  model: 'gpt-4',\n  systemPrompt: 'You are a helpful research assistant',\n  parameters: {\n    temperature: 0.7,\n    maxTokens: 2000,\n  },\n};\n\n// Validate the configuration\nconst result = validateAgentConfig(agentConfig);\n\nif (result.success) {\n  console.log('Valid config:', result.data);\n} else {\n  console.error('Validation errors:', result.error);\n}\n```\n\n### Advanced Configuration\n\n```typescript\nimport { validateAgentConfig, type AgentConfig } from '@ai-agent-schema/schema';\n\nconst advancedConfig: AgentConfig = {\n  id: 'research-agent',\n  name: 'Research Agent',\n  description: 'An agent specialized in web research and analysis',\n  provider: 'anthropic',\n  model: 'claude-3-opus-20240229',\n  systemPrompt: 'You are a research assistant with access to web search.',\n  parameters: {\n    temperature: 0.7,\n    maxTokens: 4000,\n    topP: 0.9,\n  },\n  tools: [\n    {\n      id: 'web-search',\n      name: 'Web Search',\n      description: 'Search the web for current information',\n      parameters: {\n        query: { type: 'string' },\n        maxResults: { type: 'number' },\n      },\n    },\n  ],\n  memory: {\n    type: 'buffer',\n    maxMessages: 10,\n    persistent: false,\n  },\n  connections: ['summarizer-agent'],\n  metadata: {\n    version: '1.0.0',\n    category: 'research',\n  },\n};\n\nconst result = validateAgentConfig(advancedConfig);\n```\n\n### Generate JSON Schema\n\n```typescript\nimport { generateAgentJsonSchema } from '@ai-agent-schema/schema';\n\n// Generate JSON Schema for form builders\nconst jsonSchema = generateAgentJsonSchema();\n\n// Use with react-jsonschema-form or other form generators\nconsole.log(JSON.stringify(jsonSchema, null, 2));\n```\n\n## 📚 API Reference\n\n### Types\n\n#### `AgentConfig`\n\nThe main configuration interface for an AI agent.\n\n```typescript\ninterface AgentConfig {\n  id: string;                    // Unique identifier\n  name: string;                  // Human-readable name\n  description?: string;          // Optional description\n  provider: AIProvider;          // AI model provider\n  model: string;                 // Specific model identifier\n  systemPrompt?: string;         // System instructions\n  parameters?: ModelParameters;  // Model configuration\n  tools?: Tool[];               // Available tools\n  memory?: MemoryConfig;        // Memory settings\n  connections?: string[];       // Connected agent IDs\n  metadata?: Record<string, unknown>; // Custom metadata\n}\n```\n\n#### `AIProvider`\n\nSupported AI providers:\n\n```typescript\ntype AIProvider =\n  | 'openai'\n  | 'anthropic'\n  | 'google'\n  | 'mistral'\n  | 'cohere'\n  | 'azure-openai'\n  | 'bedrock'\n  | 'custom';\n```\n\n### Functions\n\n#### `validateAgentConfig(config: unknown): ValidationResult`\n\nValidates an agent configuration and returns a result object.\n\n```typescript\nconst result = validateAgentConfig(config);\nif (result.success) {\n  // Use result.data\n} else {\n  // Handle result.error\n}\n```\n\n#### `validateAgentConfigStrict(config: unknown): AgentConfig`\n\nValidates and returns the config, or throws on error.\n\n```typescript\ntry {\n  const agent = validateAgentConfigStrict(config);\n} catch (error) {\n  console.error('Invalid config:', error);\n}\n```\n\n#### `generateAgentJsonSchema(): object`\n\nGenerates a JSON Schema representation of the agent configuration.\n\n```typescript\nconst schema = generateAgentJsonSchema();\n```\n\n### Workflow Functions\n\n#### `validateWorkflowConfig(config: unknown): WorkflowValidationResult`\n\nValidates a workflow configuration with multiple connected agents.\n\n```\n\n## 🔌 Framework Adapters\n\nAI Agent Schema includes built-in adapters to convert your agent configurations to popular AI frameworks.\n\n### n8n Adapter\n\nConvert agents and workflows to [n8n](https://n8n.io/) format:\n\n```typescript\nimport { mapAgentToN8nNode, mapWorkflowToN8n } from '@ai-agent-schema/schema';\n\n// Convert agent to n8n node\nconst n8nNode = mapAgentToN8nNode(agentConfig, {\n  startPosition: [250, 300],\n  includeCredentials: true,\n});\n\n// Convert workflow to n8n format\nconst n8nWorkflow = mapWorkflowToN8n(workflowConfig, {\n  startPosition: [250, 300],\n  nodeSpacing: 220,\n  workflowSettings: {\n    executionOrder: 'v1',\n    saveExecutionProgress: true,\n  },\n});\n\n// Import the JSON into n8n for execution\nconsole.log(JSON.stringify(n8nWorkflow, null, 2));\n```\n\n### LangChain Adapter\n\nConvert agents and workflows to [LangChain](https://www.langchain.com/) format:\n\n```typescript\nimport { mapAgentToLangChain, mapWorkflowToLangGraph } from '@ai-agent-schema/schema';\n\n// Convert agent to LangChain format\nconst lcAgent = mapAgentToLangChain(agentConfig, {\n  agentType: 'openai-functions',\n  verbose: true,\n  maxIterations: 15,\n});\n\n// Convert workflow to LangGraph format\nconst lgWorkflow = mapWorkflowToLangGraph(workflowConfig, {\n  verbose: true,\n});\n\n// Use with LangChain\nimport { StateGraph } from '@langchain/langgraph';\n\nconst graph = new StateGraph({ channels: lgWorkflow.state.schema });\n// Add nodes and edges from lgWorkflow\n```\n\n### CrewAI Adapter\n\nConvert agents and workflows to [CrewAI](https://www.crewai.com/) format:\n\n```typescript\nimport { mapAgentToCrewAgent, mapWorkflowToCrew } from '@ai-agent-schema/schema';\n\n// Convert agent to CrewAI format\nconst crewAgent = mapAgentToCrewAgent(agentConfig, {\n  verbose: true,\n  enableMemory: true,\n  enableCache: true,\n});\n\n// Convert workflow to CrewAI crew\nconst crew = mapWorkflowToCrew(workflowConfig, {\n  process: 'sequential',\n  verbose: true,\n});\n\n// Use with CrewAI\nfrom crewai import Agent, Task, Crew\n\nagents = [Agent(**agent_config) for agent_config in crew['agents']]\ntasks = [Task(**task_config) for task_config in crew['tasks']]\nmy_crew = Crew(agents=agents, tasks=tasks, process=crew['process'])\n```\n\n### Adapter Features\n\n- ✅ **Agent mapping** - Convert agent configs to framework-specific formats\n- ✅ **Workflow mapping** - Convert multi-agent workflows with connections\n- ✅ **Tool conversion** - Map tools to framework-specific tool definitions\n- ✅ **Memory mapping** - Convert memory configurations\n- ✅ **Parameter mapping** - Translate model parameters across frameworks\n- ✅ **Credential handling** - Manage API credentials appropriately\n\n## 📚 API Reference\n\n### Agent Validation\n\n#### `validateAgentConfig(config: unknown): ValidationResult`\n\nSafely validates an agent configuration.\n\n```typescript\nimport { validateAgentConfig } from '@ai-agent-schema/schema';\n\nconst result = validateAgentConfig(config);\nif (result.success) {\n  // Use result.data (typed as AgentConfig)\n} else {\n  // Handle result.error\n}\n```\n\n#### `validateAgentConfigStrict(config: unknown): AgentConfig`\n\nValidates and throws on error.\n\n```typescript\nimport { validateAgentConfigStrict } from '@ai-agent-schema/schema';\n\ntry {\n  const validConfig = validateAgentConfigStrict(config);\n} catch (error) {\n  console.error('Validation failed:', error);\n}\n```\n\n### Workflow Validation\n\n#### `validateWorkflowConfig(workflow: unknown): WorkflowValidationResult`\n\nValidates a workflow configuration with multiple connected agents.\n\n```typescript\n\n#### `detectWorkflowCycles(workflow: WorkflowConfig): boolean`\n\nDetects if a workflow has circular dependencies.\n\n```typescript\nimport { detectWorkflowCycles } from '@ai-agent-schema/schema';\n\nconst hasCycles = detectWorkflowCycles(workflow);\nif (hasCycles) {\n  console.warn('Workflow has circular dependencies');\n}\n```\n\n#### `getWorkflowTopologicalOrder(workflow: WorkflowConfig): string[] | null`\n\nGets the execution order of nodes in a workflow.\n\n```typescript\nimport { getWorkflowTopologicalOrder } from '@ai-agent-schema/schema';\n\nconst order = getWorkflowTopologicalOrder(workflow);\nif (order) {\n  console.log('Execute nodes in order:', order);\n}\n```\n\n## 🧪 Examples\n\nSee the [examples](./examples) directory for more usage examples:\n\n**Agent Examples:**\n- Basic agent configuration\n- Agent with tools and memory\n- JSON Schema generation\n\n**Workflow Examples:**\n- Simple linear workflow\n- Complex multi-agent workflow\n- Scheduled workflow with variables\n\n**Adapter Examples:**\n- n8n customer support workflow\n- LangChain research pipeline\n- CrewAI content creation crew\n\n## 🗺️ Roadmap\n\n- [x] **Phase 1**: Core schema + validator ✅\n- [x] **Phase 2**: Framework adapters (n8n, LangChain, CrewAI) ✅\n- [x] **Phase 3**: Workflow schema for multi-agent systems ✅\n- [ ] **Phase 4**: UI schema integration examples\n- [ ] **Phase 5**: Plugin ecosystem\n\n## 🤝 Contributing\n\nContributions are welcome! Please read our [Contributing Guide](./CONTRIBUTING.md) for details on:\n\n- Setting up your development environment\n- Running tests and linting\n- Code style guidelines\n- Submitting pull requests\n\n## 📄 License\n\nMIT © Shaun Ganley\n\n## 🔗 Links\n\n- [Documentation](https://github.com/shaunganley/ai-agent-schema)\n- [Issue Tracker](https://github.com/shaunganley/ai-agent-schema/issues)\n- [NPM Package](https://www.npmjs.com/package/@ai-agent-schema/schema)\n\n---\n\nBuilt with ❤️ for the AI agent community\n","readmeFilename":"README.md","_rev":"1-14ca4bea595861b92274b7d3897f6626"}