autonomous-agents 0.1.0 → 2.0.2

package/.turbo/turbo-build.log

@@ -0,0 +1,5 @@
+
+
+> autonomous-agents@2.0.1 build /Users/nathanclevenger/projects/primitives.org.ai/packages/autonomous-agents
+> tsc
+

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# autonomous-agents
+
+## 2.0.2
+
+### Patch Changes
+
+- Updated dependencies
+  - ai-functions@2.0.2
+  - digital-workers@2.0.2
+
+## 2.0.1
+
+### Patch Changes
+
+- Updated dependencies
+  - ai-functions@2.0.1
+  - digital-workers@2.0.1

package/README.md

@@ -1,144 +1,308 @@
 # autonomous-agents
 
-[![npm version](https://img.shields.io/npm/v/autonomous-agents.svg)](https://www.npmjs.com/package/autonomous-agents)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+Primitives for building and orchestrating autonomous AI agents. Implements the `digital-workers` interface for AI agents operating within a company boundary.
 
-A function-based Agent API for inherently autonomous agents. This package provides a simple, elegant way to create and manage autonomous agents that can perform actions, respond to events, and integrate with external services.
+## Overview
 
-## Purpose
+Autonomous agents are AI Workers that can:
+- Execute tasks and make decisions autonomously
+- Work in teams with other agents and humans
+- Track goals and metrics (KPIs, OKRs)
+- Request approvals and interact with human oversight
+- Operate within defined roles and responsibilities
 
-The `autonomous-agents` package embodies the definition of agents as "inherently autonomous" by providing a function-based API that:
+## Installation
 
-- Simplifies agent creation and configuration
-- Enables autonomous execution of actions based on triggers
-- Facilitates integration with external services
-- Monitors key performance indicators
-- Handles errors gracefully in an autonomous context
+```bash
+pnpm add autonomous-agents
+```
 
-## How It Differs from agents.do SDK
+## Integration with digital-workers
 
-The `autonomous-agents` package represents a transition from the class-based approach used in the existing agents.do SDK to a more modern, function-based API. Key differences include:
+Autonomous agents implement the `Worker` interface from `digital-workers`, enabling them to:
+- Receive notifications, questions, and approval requests
+- Be targeted by Worker Actions in workflows
+- Communicate through configured contact channels
 
-- **Function-based API**: Uses a functional approach instead of classes, aligning with modern JavaScript/TypeScript practices
-- **Simplified Configuration**: Provides a more intuitive configuration interface
-- **Enhanced Autonomy**: Built with autonomy as a core principle rather than an add-on feature
-- **Improved Error Handling**: Designed with robust error handling for autonomous operations
-- **Performance Monitoring**: Integrated tracking of key results and performance metrics
+```typescript
+import { Agent } from 'autonomous-agents'
+import { registerWorkerActions, withWorkers } from 'digital-workers'
+import { Workflow } from 'ai-workflows'
+
+// Create an autonomous agent
+const codeReviewer = Agent({
+  name: 'Code Reviewer',
+  role: Role({
+    name: 'Senior Engineer',
+    description: 'Reviews code for quality and security',
+    skills: ['code review', 'security analysis'],
+  }),
+  mode: 'autonomous',
+  contacts: {
+    api: { endpoint: 'https://api.internal/reviewer', auth: 'bearer' },
+    webhook: { url: 'https://hooks.internal/code-review' },
+  },
+})
 
-## Installation
+// Use in workflows
+const workflow = Workflow($ => {
+  registerWorkerActions($)
+  const worker$ = withWorkers($)
+
+  $.on.PR.opened(async (pr) => {
+    // Ask the AI agent to review
+    const review = await worker$.ask(
+      codeReviewer,
+      `Review PR #${pr.number}: ${pr.title}`,
+      { schema: { approved: 'boolean', comments: ['string'] } }
+    )
+
+    if (!review.approved) {
+      await worker$.notify(pr.author, `Code review needs changes: ${review.comments.join(', ')}`)
+    }
+  })
+})
+```
 
-```bash
-# Using npm
-npm install autonomous-agents
+## Creating Agents
 
-# Using yarn
-yarn add autonomous-agents
+### Basic Agent
 
-# Using pnpm
-pnpm add autonomous-agents
-```
+```typescript
+import { Agent, Role } from 'autonomous-agents'
+
+const productManager = Role({
+  name: 'Product Manager',
+  description: 'Manages product strategy and roadmap',
+  skills: ['product strategy', 'user research', 'roadmap planning'],
+})
+
+const agent = Agent({
+  name: 'ProductAgent',
+  role: productManager,
+  mode: 'autonomous',
+  goals: [
+    { id: 'g1', description: 'Define Q1 roadmap', target: '100%' }
+  ],
+})
+
+// Execute tasks
+const result = await agent.do('Create product brief for feature X')
+
+// Make decisions
+const choice = await agent.decide(['A', 'B', 'C'], 'Which feature to prioritize?')
 
-## Usage
+// Ask questions
+const answer = await agent.ask('What are the top user complaints?')
+```
 
-### Basic Usage
+### Supervised Agent
 
 ```typescript
-import { Agent } from 'autonomous-agents'
+const supervisedAgent = Agent({
+  name: 'DeployBot',
+  role: Role({
+    name: 'DevOps Engineer',
+    description: 'Manages deployments',
+    skills: ['deployment', 'infrastructure'],
+  }),
+  mode: 'supervised',
+  supervisor: 'alice@company.com', // Human supervisor
+  requiresApproval: true,
+  contacts: {
+    slack: { workspace: 'company', channel: '#deployments' },
+  },
+})
 
-// Create a customer support agent
-const amy = Agent({
-  name: 'Amy',
-  url: 'https://amy.do',
-  role: 'Customer Support Agent',
-  objective: 'Handles customer inquiries and resolves common issues',
-  keyResults: ['ticketResponseTime', 'ticketResolutionTime', 'customerSatisfaction'],
-  integrations: ['chat', 'slack', 'email', 'zendesk', 'shopify'],
-  triggers: ['onTicketCreated', 'onMessageReceived'],
-  searches: ['FAQs', 'Tickets', 'Orders', 'Products', 'Customers'],
-  actions: ['sendMessage', 'updateOrder', 'refundOrder', 'resolveTicket', 'escalateTicket'],
+// This will request approval before executing
+const approval = await supervisedAgent.approve({
+  title: 'Production Deployment',
+  description: 'Deploy v2.0.0 to production',
+  data: { version: '2.0.0', environment: 'production' },
+  priority: 'high',
 })
+
+if (approval.status === 'approved') {
+  await supervisedAgent.do('Deploy application', { version: '2.0.0' })
+}
 ```
 
-### Executing Actions
+## Teams
+
+Create teams of agents and humans:
 
 ```typescript
-// Execute an action using the 'do' proxy
-const result = await amy.do('sendMessage', {
-  recipient: 'customer@example.com',
-  subject: 'Order Status Update',
-  body: 'Your order has been shipped and will arrive in 2-3 business days.'
+import { Team, Agent, Role } from 'autonomous-agents'
+
+const engineeringTeam = Team({
+  name: 'Engineering',
+  description: 'Product engineering team',
+  members: [
+    {
+      id: 'alice',
+      name: 'Alice',
+      role: Role({ name: 'Tech Lead', description: 'Leads technical decisions', skills: [] }),
+      type: 'human',
+    },
+    {
+      id: 'code-reviewer',
+      name: 'Code Reviewer Bot',
+      role: Role({ name: 'Reviewer', description: 'Reviews code', skills: ['code review'] }),
+      type: 'agent',
+    },
+  ],
+  goals: [
+    { id: 'velocity', description: 'Increase velocity by 20%', target: '20%' },
+  ],
+  channels: [
+    { id: 'slack', type: 'slack', config: { channel: '#engineering' } },
+  ],
 })
 
-// Execute a custom operation
-const customResult = await amy.execute({
-  operation: 'processRefund',
-  orderId: '12345',
-  amount: 99.99,
-  reason: 'Customer request'
-})
+// Find best team member for a task
+const reviewer = findBestMemberForTask(engineeringTeam, 'code review')
 ```
 
-### Handling Events
+## Goals and OKRs
+
+Track agent goals with KPIs and OKRs:
 
 ```typescript
-// Set up an event handler for a trigger
-amy.onTicketCreated(async (ticket) => {
-  console.log(`New ticket created: ${ticket.id}`)
-  
-  // Automatically respond to the ticket
-  await amy.do('sendMessage', {
-    ticketId: ticket.id,
-    message: 'Thank you for your inquiry. We will respond shortly.'
-  })
+import { Goals, kpis, okrs } from 'autonomous-agents'
+
+const agentGoals = Goals({
+  goals: [
+    {
+      id: 'response-time',
+      description: 'Maintain sub-5s response time',
+      target: '5s',
+      priority: 'high',
+      successCriteria: ['95th percentile < 5s', 'No timeouts'],
+    },
+  ],
+  strategy: 'Focus on performance optimization',
 })
+
+// Define KPIs
+const performanceKPIs = kpis([
+  {
+    id: 'response-time',
+    name: 'Response Time',
+    value: 3.2,
+    target: 5,
+    unit: 'seconds',
+    trend: 'down', // lower is better
+  },
+  {
+    id: 'success-rate',
+    name: 'Success Rate',
+    value: 98.5,
+    target: 99,
+    unit: '%',
+    trend: 'up',
+  },
+])
+
+// Define OKRs
+const quarterlyOKRs = okrs([
+  {
+    id: 'okr-1',
+    objective: 'Improve agent reliability',
+    keyResults: [
+      { id: 'kr-1', description: 'Reduce error rate', current: 2, target: 0.5, unit: '%' },
+      { id: 'kr-2', description: 'Increase uptime', current: 99.5, target: 99.9, unit: '%' },
+    ],
+    period: 'Q1 2024',
+    status: 'active',
+  },
+])
 ```
 
-## API Reference
+## Action Primitives
 
-### Agent(config)
+Standalone action functions:
 
-Creates a new autonomous agent with the provided configuration.
+```typescript
+import { do as doTask, ask, decide, approve, generate, is, notify } from 'autonomous-agents'
 
-**Parameters:**
+// Execute a task
+const result = await doTask('Analyze customer feedback', {
+  feedback: ['Great!', 'Needs work', 'Love it'],
+})
 
-- `config` (AgentConfig): The configuration for the agent
+// Ask a question
+const answer = await ask('What are the key benefits?', { product: 'AI Assistant' })
 
-**Returns:**
+// Make a decision
+const choice = await decide(['React', 'Vue', 'Svelte'], 'Best framework for this project')
 
-- (AutonomousAgent): An autonomous agent instance
+// Request approval
+const approval = await approve({
+  title: 'Budget Request',
+  description: 'Request $50k for research',
+  data: { amount: 50000 },
+  approver: 'manager@company.com',
+  channel: 'slack',
+})
+
+// Generate content
+const content = await generate({
+  schema: { title: 'string', body: 'string' },
+  prompt: 'Write a blog post about AI',
+})
+
+// Type validation
+const isValid = await is({ email: 'test@example.com' }, 'valid email address')
+
+// Send notification
+await notify({
+  message: 'Task completed!',
+  channel: 'slack',
+  recipients: ['#general'],
+})
+```
 
-### AgentConfig
+## Role Definitions
 
-The configuration object for creating an agent.
+Define agent capabilities through roles:
 
-| Property | Type | Description |
-|----------|------|-------------|
-| name | string | The name of the agent |
-| url | string | The URL associated with the agent |
-| role | string | The role or purpose of the agent |
-| objective | string | The main objective or goal of the agent |
-| keyResults | string[] | Key performance indicators for the agent |
-| integrations | string[] | External services the agent can integrate with |
-| triggers | string[] | Events that the agent can respond to |
-| searches | string[] | Types of searches the agent can perform |
-| actions | string[] | Actions that the agent can perform |
+```typescript
+import { Role, Roles, hasSkill, getPermissions } from 'autonomous-agents'
+
+// Create a role
+const securityAnalyst = Role({
+  name: 'Security Analyst',
+  description: 'Analyzes code for security vulnerabilities',
+  skills: ['security analysis', 'code review', 'vulnerability assessment'],
+  permissions: ['read-code', 'create-issues', 'request-changes'],
+})
 
-### AutonomousAgent
+// Check capabilities
+if (hasSkill(securityAnalyst, 'security analysis')) {
+  // Assign security review
+}
 
-The agent instance returned by the Agent function.
+// Common roles
+const { ProductManager, SoftwareEngineer, DataAnalyst } = Roles
+```
 
-| Property/Method | Type | Description |
-|-----------------|------|-------------|
-| config | AgentConfig | The configuration of the agent |
-| execute | (input: Record<string, any>, options?: any) => Promise<any> | Executes a custom operation |
-| do | Proxy | A proxy for executing actions defined in the agent's configuration |
-| [triggerName] | Function | Dynamic event handlers for each trigger defined in the agent's configuration |
+## Type Reference
 
-## Dependencies
+Key types exported:
 
-- TypeScript: For type safety and developer experience
-- No external runtime dependencies, ensuring a lightweight package
+- `Agent` / `AgentType` - Agent interface and configuration
+- `AgentConfig` - Agent configuration options
+- `AgentMode` - 'autonomous' | 'supervised' | 'manual'
+- `Role` / `RoleType` - Role definitions
+- `Team` / `TeamType` - Team composition
+- `Goal` - Goal definitions
+- `KPI` - Key Performance Indicators
+- `OKR` - Objectives and Key Results
+- `ApprovalRequest` / `ApprovalResult` - Approval workflow types
 
-## License
+## Related Packages
 
-MIT
+- `digital-workers` - Common Worker interface for agents and humans
+- `ai-workflows` - Event-driven workflow engine
+- `human-in-the-loop` - Human oversight patterns
+- `ai-functions` - AI function primitives

package/dist/actions.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Actions - Core action functions for autonomous agents
+ *
+ * These are standalone functions that can be used independently
+ * or as part of an agent's capabilities.
+ *
+ * @packageDocumentation
+ */
+import { type AIGenerateOptions, type SimpleSchema } from 'ai-functions';
+import type { ApprovalRequest, ApprovalResult, NotificationOptions } from './types.js';
+/**
+ * Execute a task using AI
+ *
+ * @example
+ * ```ts
+ * import { do as doTask } from 'autonomous-agents'
+ *
+ * const result = await doTask('Analyze customer feedback and provide insights', {
+ *   feedback: ['Great product!', 'Needs improvement', 'Love the features'],
+ * })
+ * ```
+ */
+export declare function doAction<TResult = unknown>(task: string, context?: unknown, options?: AIGenerateOptions): Promise<TResult>;
+/**
+ * Ask a question and get an answer
+ *
+ * @example
+ * ```ts
+ * import { ask } from 'autonomous-agents'
+ *
+ * const answer = await ask('What are the key benefits of our product?', {
+ *   product: 'AI Assistant',
+ *   features: ['smart automation', 'natural language', 'context awareness'],
+ * })
+ * ```
+ */
+export declare function ask<TResult = unknown>(question: string, context?: unknown, options?: AIGenerateOptions): Promise<TResult>;
+/**
+ * Make a decision between options
+ *
+ * @example
+ * ```ts
+ * import { decide } from 'autonomous-agents'
+ *
+ * const choice = await decide(
+ *   ['option A', 'option B', 'option C'],
+ *   'Which option has the highest ROI?'
+ * )
+ * ```
+ */
+export declare function decide<T extends string>(options: T[], context?: string, settings?: AIGenerateOptions): Promise<T>;
+/**
+ * Request approval for an action or decision
+ *
+ * @example
+ * ```ts
+ * import { approve } from 'autonomous-agents'
+ *
+ * const approval = await approve({
+ *   title: 'Budget Request',
+ *   description: 'Request $50k for marketing campaign',
+ *   data: { amount: 50000, campaign: 'Q1 Launch' },
+ *   approver: 'manager@company.com',
+ *   priority: 'high',
+ * })
+ *
+ * if (approval.status === 'approved') {
+ *   // Proceed with the action
+ * }
+ * ```
+ */
+export declare function approve<TResult = unknown>(request: ApprovalRequest): Promise<ApprovalResult<TResult>>;
+/**
+ * Execute approval request (internal implementation)
+ */
+export declare function executeApproval<TResult = unknown>(request: ApprovalRequest): Promise<ApprovalResult<TResult>>;
+/**
+ * Generate content using AI
+ *
+ * @example
+ * ```ts
+ * import { generate } from 'autonomous-agents'
+ *
+ * const content = await generate({
+ *   model: 'sonnet',
+ *   schema: {
+ *     title: 'Blog post title',
+ *     content: 'Blog post content',
+ *     tags: ['List of tags'],
+ *   },
+ *   prompt: 'Write a blog post about AI automation',
+ * })
+ * ```
+ */
+export declare function generate<TResult = unknown>(options: AIGenerateOptions): Promise<TResult>;
+/**
+ * Type checking and validation
+ *
+ * @example
+ * ```ts
+ * import { is } from 'autonomous-agents'
+ *
+ * const isValid = await is(
+ *   { email: 'test@example.com' },
+ *   'valid email address'
+ * )
+ *
+ * const matchesSchema = await is(
+ *   { name: 'John', age: 30 },
+ *   { name: 'string', age: 'number' }
+ * )
+ * ```
+ */
+export declare function is(value: unknown, type: string | SimpleSchema): Promise<boolean>;
+/**
+ * Send a notification
+ *
+ * @example
+ * ```ts
+ * import { notify } from 'autonomous-agents'
+ *
+ * await notify({
+ *   message: 'Task completed successfully!',
+ *   channel: 'slack',
+ *   recipients: ['#general'],
+ *   priority: 'high',
+ *   data: { taskId: '123', duration: '5 minutes' },
+ * })
+ * ```
+ */
+export declare function notify(options: NotificationOptions): Promise<void>;
+/**
+ * Export the 'do' function with an alias to avoid keyword conflict
+ */
+export { doAction as do };
+//# sourceMappingURL=actions.d.ts.map

package/dist/actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAkB,KAAK,iBAAiB,EAAE,KAAK,YAAY,EAAE,MAAM,cAAc,CAAA;AACxF,OAAO,KAAK,EACV,eAAe,EACf,cAAc,EAEd,mBAAmB,EACpB,MAAM,YAAY,CAAA;AAEnB;;;;;;;;;;;GAWG;AACH,wBAAsB,QAAQ,CAAC,OAAO,GAAG,OAAO,EAC9C,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,OAAO,EACjB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,OAAO,CAAC,CAUlB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,GAAG,CAAC,OAAO,GAAG,OAAO,EACzC,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,OAAO,EACjB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,OAAO,CAAC,CAclB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,MAAM,CAAC,CAAC,SAAS,MAAM,EAC3C,OAAO,EAAE,CAAC,EAAE,EACZ,OAAO,CAAC,EAAE,MAAM,EAChB,QAAQ,CAAC,EAAE,iBAAiB,GAC3B,OAAO,CAAC,CAAC,CAAC,CAoBZ;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,OAAO,CAAC,OAAO,GAAG,OAAO,EAC7C,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAElC;AAED;;GAEG;AACH,wBAAsB,eAAe,CAAC,OAAO,GAAG,OAAO,EACrD,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAkClC;AAiCD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,QAAQ,CAAC,OAAO,GAAG,OAAO,EAC9C,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,OAAO,CAAC,CAUlB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,EAAE,CACtB,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,MAAM,GAAG,YAAY,GAC1B,OAAO,CAAC,OAAO,CAAC,CAclB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,MAAM,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CA6BxE;AAiCD;;GAEG;AACH,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,CAAA"}