{"_id":"@apptrix/automata-agent-consumer","_rev":"3-61428960ed7a0d4ff22bd5a956817d92","name":"@apptrix/automata-agent-consumer","dist-tags":{"latest":"1.0.3"},"versions":{"1.0.1":{"name":"@apptrix/automata-agent-consumer","version":"1.0.1","keywords":["agent","consumer","sdk","automata"],"license":"MIT","_id":"@apptrix/automata-agent-consumer@1.0.1","maintainers":[{"name":"heliomendes","email":"helio5_mendes@hotmail.com"}],"dist":{"shasum":"f2284e38c84135c50e0dbc097d880ede08e7afe5","tarball":"https://registry.npmjs.org/@apptrix/automata-agent-consumer/-/automata-agent-consumer-1.0.1.tgz","fileCount":30,"integrity":"sha512-gdfYErwT63uvRZ97R8g8GY2RX1jw2aF+ny78OPq3vx0C3XCLDG5xPPNc34Kalhywt1amgWeWcBBw9d/mHltjbw==","signatures":[{"sig":"MEUCIBN3fglq18H6ziVxMSDEXRXBo6Yf5W3x+feHQGOVA628AiEA/f4AGRmLsGZ+8nE9TpVIDwFHsM4QB8lMe1RuckidVHU=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":202406},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","scripts":{"dev":"tsx watch example.ts","build":"tsc","example":"tsx example.ts","prepare":"npm run build","ai-search":"tsx ai-search-agent.ts"},"_npmUser":{"name":"heliomendes","email":"helio5_mendes@hotmail.com"},"_npmVersion":"10.8.2","description":"SDK for creating service consumer agents","directories":{},"_nodeVersion":"22.5.1","dependencies":{"dotenv":"^16.4.5","jsonwebtoken":"^9.0.2","@types/jsonwebtoken":"^9.0.10"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.7.0","typescript":"^5.3.3","@types/node":"^20.10.5"},"_npmOperationalInternal":{"tmp":"tmp/automata-agent-consumer_1.0.1_1764876531949_0.5671600351618751","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@apptrix/automata-agent-consumer","version":"1.0.2","keywords":["agent","consumer","sdk","automata"],"license":"MIT","_id":"@apptrix/automata-agent-consumer@1.0.2","maintainers":[{"name":"heliomendes","email":"helio5_mendes@hotmail.com"}],"dist":{"shasum":"cd595d70b0bca75953f810091d1a2bec97d75151","tarball":"https://registry.npmjs.org/@apptrix/automata-agent-consumer/-/automata-agent-consumer-1.0.2.tgz","fileCount":30,"integrity":"sha512-Tpj8RrtH619Sx9BCvKSX9CPodfMXAYrYqmLQ9zbzaGfUjodk9LtCxpFri7/7Tudhse8x8oisfZKbhSdZ1cSNqA==","signatures":[{"sig":"MEUCIDbDN/rfoh1Ds+pWQ5KlmiLcb0xXImWtzQbKr0blx/2KAiEArgh3Jppp+nbe9HxnMHdFTVrVglYYKiw0aMmZt1pBf3o=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":204575},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","gitHead":"2162c13bb35776e41142ff55d601e1deb985990e","scripts":{"dev":"tsx watch example.ts","build":"tsc","example":"tsx example.ts","prepare":"npm run build","ai-search":"tsx ai-search-agent.ts"},"_npmUser":{"name":"heliomendes","email":"helio5_mendes@hotmail.com"},"_npmVersion":"10.8.2","description":"SDK for creating service consumer agents","directories":{},"_nodeVersion":"22.5.1","dependencies":{"dotenv":"^16.4.5","jsonwebtoken":"^9.0.2","@types/jsonwebtoken":"^9.0.10"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.7.0","typescript":"^5.3.3","@types/node":"^20.10.5"},"_npmOperationalInternal":{"tmp":"tmp/automata-agent-consumer_1.0.2_1765122775442_0.8147144502244466","host":"s3://npm-registry-packages-npm-production"}},"1.0.3":{"name":"@apptrix/automata-agent-consumer","version":"1.0.3","description":"SDK for creating service consumer agents","main":"dist/index.js","types":"dist/index.d.ts","type":"module","scripts":{"build":"tsc","dev":"tsx watch example.ts","example":"tsx example.ts","ai-search":"tsx ai-search-agent.ts","prepare":"npm run build"},"keywords":["agent","consumer","sdk","automata"],"publishConfig":{"access":"public"},"license":"MIT","devDependencies":{"@types/node":"^20.10.5","tsx":"^4.7.0","typescript":"^5.3.3"},"dependencies":{"@types/jsonwebtoken":"^9.0.10","dotenv":"^16.4.5","jsonwebtoken":"^9.0.2"},"_id":"@apptrix/automata-agent-consumer@1.0.3","gitHead":"8990ca062daeb99fd097c86c625aa031565553f7","_nodeVersion":"22.5.1","_npmVersion":"10.8.2","dist":{"integrity":"sha512-ami91dSxVuScqyUlWvpuy7E9ijCghM7l9nNZSiP/A5nvt/cd1X9m4qH16NTGD1ah0awHZwnip1Y6sPfJN0jyTg==","shasum":"a10d749528cd53d69197ea9fb2a513fd01a26fd8","tarball":"https://registry.npmjs.org/@apptrix/automata-agent-consumer/-/automata-agent-consumer-1.0.3.tgz","fileCount":30,"unpackedSize":205379,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQC8gX4nNj0FddWhLTVQZdz3V8uAZlJtoEv7EzzZGtMtygIgdliimO30DJapFGdIulb5UDQ8Y2R/bOWqBZ8MetLkKAk="}]},"_npmUser":{"name":"heliomendes","email":"helio5_mendes@hotmail.com"},"directories":{},"maintainers":[{"name":"heliomendes","email":"helio5_mendes@hotmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/automata-agent-consumer_1.0.3_1765195700735_0.0528211122137936"},"_hasShrinkwrap":false}},"time":{"created":"2025-12-04T19:28:51.824Z","modified":"2025-12-08T12:08:21.082Z","1.0.1":"2025-12-04T19:28:52.104Z","1.0.2":"2025-12-07T15:52:55.608Z","1.0.3":"2025-12-08T12:08:20.876Z"},"license":"MIT","keywords":["agent","consumer","sdk","automata"],"description":"SDK for creating service consumer agents","maintainers":[{"name":"heliomendes","email":"helio5_mendes@hotmail.com"}],"readme":"# Agent Consumer SDK\r\n\r\n**Discover, execute, and orchestrate AI-powered service agents from the Automata Registry**\r\n\r\nThe Consumer SDK lets you search for specialized agents using natural language, execute them with automatic validation, and receive intelligent responses - all with built-in LLM integration.\r\n\r\n---\r\n\r\n## Why Use This SDK?\r\n\r\n✅ **Smart Discovery**: Find agents using natural language - the LLM automatically extracts intents, categories, and keywords\r\n✅ **Automatic Validation**: Built-in input schema validation ensures you send valid parameters\r\n✅ **Multi-Agent Orchestration**: Execute multiple agents in parallel and get a unified AI-interpreted response\r\n✅ **Feedback Loop**: Automatic performance tracking improves agent rankings over time\r\n✅ **Multi-Language**: Works in any language - the LLM adapts naturally\r\n\r\n---\r\n\r\n## Installation\r\n\r\n```bash\r\nnpm install @apptrix/automata-agent-consumer\r\n```\r\n\r\n---\r\n\r\n## Quick Start\r\n\r\n```typescript\r\nimport { AgentConsumer } from '@apptrix/automata-agent-consumer';\r\n\r\nconst consumer = new AgentConsumer({\r\n  llm: {\r\n    provider: 'openai',\r\n    apiKey: process.env.LLM_API_KEY!,\r\n    model: 'gpt-4o-mini',\r\n    temperature: 0.7,\r\n  },\r\n  userLanguage: 'en-US', // Optional - LLM adapts to any language\r\n});\r\n\r\nawait consumer.authenticate();\r\n\r\n// Natural language input\r\nconst userInput = \"I need a Japanese restaurant in Copacabana with good prices\";\r\n\r\n// LLM analyzes and extracts structured data\r\nconst analysis = await consumer.analyzePrompt(userInput);\r\n\r\nconsole.log('Intents:', analysis.intents);\r\n// Output: ['food.restaurant.search', 'service.dining.search']\r\n\r\nconsole.log('Categories:', analysis.categories);\r\n// Output: ['food', 'cuisine:japanese']\r\n\r\n// Search agents in the registry\r\nconst agents = await consumer.search({\r\n  intent: analysis.intents,  // Can pass array or single intent\r\n  categories: analysis.categories,\r\n  tags: analysis.keywords,\r\n  location: analysis.location,\r\n  limit: 10,\r\n});\r\n\r\n// AI filters semantically irrelevant agents AND selects appropriate tasks\r\nconst relevantAgents = await consumer.validateAgentRelevance(agents, analysis);\r\n\r\n// Execute all relevant agents with automatic feedback\r\n// Note: selectedTask is automatically used if available\r\nconst results = await consumer.executeMultipleWithFeedback(\r\n  relevantAgents,\r\n  {\r\n    task: 'search_restaurants',  // Fallback task\r\n    params: {\r\n      cuisine: 'japanese',\r\n      location: 'Copacabana',\r\n    },\r\n  },\r\n  {\r\n    userPrompt: userInput,\r\n    analysis,\r\n  }\r\n);\r\n\r\n// Interpretation is automatically done inside executeMultipleWithFeedback\r\n// Access it via _interpretation property\r\nconsole.log(results._interpretation);  // Final message for user\r\n```\r\n\r\n---\r\n\r\n## 🎯 Understanding Discovery: Intents, Categories, and Tags\r\n\r\nThe Registry uses **three key fields** to match consumers with providers:\r\n\r\n### 1. **Intents** (Most Specific)\r\nIntents describe the **exact action** using dot notation.\r\n\r\n**Examples:**\r\n- `food.restaurant.search` - Search for restaurants\r\n- `travel.hotel.book` - Book a hotel room\r\n- `finance.invoice.generate` - Generate invoices\r\n- `communication.email.send` - Send emails\r\n\r\n**When to use:** Use intents when you need a very specific action. The LLM automatically extracts intents from natural language.\r\n\r\n### 2. **Categories** (Hierarchical Grouping)\r\nCategories use `general:subcategory` format for precise filtering.\r\n\r\n**Format:** `general:subcategory` (e.g., `hospitality:luxury`, `cuisine:italian`)\r\n\r\n**Examples:**\r\n- `['food', 'cuisine:japanese']` - Japanese cuisine\r\n- `['travel', 'hospitality:luxury']` - Luxury hotels\r\n- `['finance', 'product:investment']` - Investment products\r\n- `['development', 'tech:react']` - React development\r\n\r\n**When to use:** Use specific subcategories when you need precise filtering, or just the general category for broader searches.\r\n\r\n### 3. **Tags** (Free-Form Keywords)\r\nTags are flexible keywords for additional filtering.\r\n\r\n**Examples:**\r\n- `['japanese', 'copacabana', 'budget-friendly']`\r\n- `['luxury', 'beachfront', 'family-friendly']`\r\n- `['api', 'real-time', 'webhook']`\r\n\r\n**When to use:** Use tags for attributes, features, locations, or other descriptive keywords.\r\n\r\n---\r\n\r\n## 🔍 Search Best Practices\r\n\r\n### Strategy 1: Intent-First (Precise)\r\nWhen you know **exactly** what you need:\r\n\r\n```typescript\r\nconst agents = await consumer.search({\r\n  intent: 'travel.hotel.search',\r\n  categories: ['travel', 'hospitality:luxury'],\r\n  tags: ['pool', 'beachfront'],\r\n  location: 'Miami,Florida,USA',\r\n  limit: 5,\r\n});\r\n```\r\n\r\n### Strategy 2: Category-First (Exploratory)\r\nWhen you want to **discover** what's available:\r\n\r\n```typescript\r\nconst agents = await consumer.search({\r\n  categories: ['food', 'venue:delivery'], // Delivery restaurants\r\n  tags: ['vegan', 'budget-friendly'],\r\n  location: 'San Francisco,California,USA',\r\n  limit: 20,\r\n});\r\n```\r\n\r\n### Strategy 3: LLM-Powered (Natural Language)\r\nLet the **LLM extract everything**:\r\n\r\n```typescript\r\nconst analysis = await consumer.analyzePrompt(\r\n  \"Find me a pet-friendly hotel in Miami Beach with ocean view\"\r\n);\r\n\r\nconst agents = await consumer.search({\r\n  intent: analysis.intents,          // LLM extracts: ['travel.hotel.search', 'service.booking.search']\r\n  categories: analysis.categories,   // LLM extracts: ['travel', 'hospitality:luxury']\r\n  tags: analysis.keywords,           // LLM extracts: ['pet-friendly', 'ocean-view']\r\n  location: analysis.location,       // LLM extracts: Miami Beach,Florida,USA\r\n  description: analysis.description, // LLM summary\r\n  limit: 10,\r\n});\r\n```\r\n\r\n> **💡 Recommended:** Use Strategy 3 for the best user experience. The LLM handles language, synonyms, and context automatically.\r\n\r\n---\r\n\r\n## 🛡️ Input Schema Validation\r\n\r\nWhen agents define an `input_schema`, the SDK validates parameters before execution:\r\n\r\n```typescript\r\n// Agent defines this schema:\r\n{\r\n  \"type\": \"object\",\r\n  \"properties\": {\r\n    \"city\": { \"type\": \"string\" },\r\n    \"checkIn\": { \"type\": \"string\", \"format\": \"date\" },\r\n    \"guests\": { \"type\": \"number\" }\r\n  },\r\n  \"required\": [\"city\", \"checkIn\"]\r\n}\r\n\r\n// SDK validates automatically:\r\nconst result = await consumer.executeWithFeedback(agent, {\r\n  task: 'book_hotel',\r\n  params: {\r\n    city: 'Miami',\r\n    checkIn: '2025-03-15',\r\n    guests: 2,\r\n  },\r\n});\r\n// ✅ Validation passes, executes normally\r\n\r\nconst badResult = await consumer.executeWithFeedback(agent, {\r\n  task: 'book_hotel',\r\n  params: {\r\n    guests: 2, // Missing required 'city' and 'checkIn'\r\n  },\r\n});\r\n// ❌ Returns: { success: false, error: \"Input validation failed: Missing required field: city, Missing required field: checkIn\" }\r\n```\r\n\r\n**Schema-Aware Execution:**\r\nWhen using `executeMultipleWithFeedback`, the SDK sends the provider's `input_schema` to the LLM so it can build valid params:\r\n\r\n```typescript\r\nconst results = await consumer.executeMultipleWithFeedback(\r\n  agents,\r\n  {\r\n    task: 'book_hotel',\r\n    params: {}, // LLM will populate this based on schema + user prompt\r\n  },\r\n  {\r\n    userPrompt: \"Book a hotel in Miami for March 15th, 2 guests\",\r\n    analysis,\r\n  }\r\n);\r\n```\r\n\r\nThe LLM reads each agent's `input_schema`, maps the natural language prompt to valid params, and tracks agents with missing fields in `consumer.getPendingAgents()` for retry.\r\n\r\n---\r\n\r\n## 🤖 LLM Features\r\n\r\n### `analyzePrompt(userPrompt)`\r\nExtracts structured data from natural language.\r\n\r\n**Input:** `\"Find me a vegan restaurant in Tokyo with outdoor seating\"`\r\n\r\n**Output:**\r\n```typescript\r\n{\r\n  intents: ['food.restaurant.search', 'service.dining.search'],  // Array of 2-3 alternative intents\r\n  categories: ['food', 'cuisine:vegan', 'venue:cafe'],\r\n  keywords: ['vegan', 'outdoor-seating', 'tokyo'],\r\n  tags: ['vegan', 'outdoor', 'tokyo'],\r\n  features: ['outdoor seating', 'vegan options'],\r\n  location: 'Tokyo,Japan',\r\n  description: 'User wants to find a vegan restaurant in Tokyo with outdoor seating',\r\n  language: 'en-US'\r\n}\r\n```\r\n\r\n**Note:** If the user mentions a brand name (like \"Carrefour\", \"Apple\", etc.), the SDK automatically includes a brand-specific intent like `brand.carrefour` in the intents array.\r\n\r\n### `validateAgentRelevance(agents, analysis)`\r\nUses semantic understanding to filter out irrelevant agents **AND** selects the appropriate task for each agent.\r\n\r\n**Why?** Keyword matching can return false positives. The LLM validates that each agent *actually* solves the user's need and picks the best task from the agent's available tasks.\r\n\r\n```typescript\r\n// Search might return 10 agents matching \"hotel\" and \"Miami\"\r\nconst agents = await consumer.search({ ... });\r\n\r\n// LLM filters to only relevant ones AND assigns selectedTask to each agent\r\nconst relevant = await consumer.validateAgentRelevance(agents, analysis);\r\n\r\n// Each relevant agent now has a selectedTask property\r\n// relevant[0].selectedTask === \"get_quote\" (for example)\r\n```\r\n\r\n**Returns:** Filtered `AgentInfo[]` where each agent has a `selectedTask` property set by the LLM.\r\n\r\n### `interpretResponses(userRequest, agentResponses, intent)`\r\nCombines multiple agent responses into a natural, conversational answer **and rates each agent's relevance**.\r\n\r\n**Input:** 3 hotel agents return JSON with availability and prices\r\n\r\n**Output:**\r\n```typescript\r\n{\r\n  message: `I found 3 hotels for you in Miami Beach:\r\n\r\n1. **Ocean View Resort** - $250/night, beachfront, pet-friendly\r\n2. **Downtown Suites** - $180/night, city center, business amenities\r\n3. **Budget Inn** - $95/night, basic accommodation\r\n\r\nBased on your request for ocean view and pet-friendly, I recommend Ocean View Resort.`,\r\n\r\n  agentRatings: {\r\n    'agent:hotel:miami:oceanview': 0.95,  // Highly relevant\r\n    'agent:hotel:miami:downtown': 0.7,     // Moderately relevant\r\n    'agent:hotel:miami:budget': 0.5        // Less relevant\r\n  }\r\n}\r\n```\r\n\r\n**Returns:** `{ message: string; agentRatings: Record<string, number> }`\r\n\r\nThe `agentRatings` are automatically used to compute feedback scores sent to the Registry, improving future rankings.\r\n\r\n---\r\n\r\n## 📚 API Reference\r\n\r\n### Constructor\r\n\r\n```typescript\r\nnew AgentConsumer(config: AgentConsumerConfig)\r\n```\r\n\r\n**Config:**\r\n```typescript\r\ninterface AgentConsumerConfig {\r\n  llm: {\r\n    provider: 'openai' | 'claude' | 'gemini' | 'deepseek' | 'openrouter';\r\n    apiKey: string;\r\n    model: string;\r\n    temperature?: number; // Default: 0.7\r\n  };\r\n  userLanguage?: string;      // Default: 'en-US'\r\n  registryUrl?: string;        // Optional - auto-detected based on NODE_ENV\r\n}\r\n```\r\n\r\n### Authentication\r\n\r\n```typescript\r\nawait consumer.authenticate(): Promise<void>\r\n```\r\n\r\nAuthenticates with Registry Central and obtains a JWT token.\r\n\r\n### Search\r\n\r\n```typescript\r\nawait consumer.search(request: SearchRequest): Promise<AgentInfo[]>\r\n```\r\n\r\n**SearchRequest:**\r\n```typescript\r\ninterface SearchRequest {\r\n  intent?: string | string[];  // Single intent or array (e.g., 'food.restaurant.search' or ['food.restaurant.search', 'brand.carrefour'])\r\n  categories: string[];        // e.g., ['food', 'restaurant.search']\r\n  tags?: string[];             // e.g., ['japanese', 'budget']\r\n  location?: string;           // e.g., 'Tokyo,Japan'\r\n  language?: string;           // e.g., 'en-US'\r\n  description?: string;        // Natural description\r\n  limit?: number;              // Max results (default: 10)\r\n}\r\n```\r\n\r\n**Returns:**\r\n```typescript\r\ninterface AgentInfo {\r\n  id: string;\r\n  name: string;\r\n  endpoint: string;\r\n  description: string;\r\n  tags: string[];\r\n  intents: string[];\r\n  tasks: string[];              // Available tasks for this agent\r\n  categories: string[];\r\n  location_scope: string;\r\n  score: number;\r\n  execution_key?: string;\r\n  key_expires_at?: Date;\r\n  input_schema?: Record<string, any>;\r\n  selectedTask?: string;        // Task selected by LLM after validation\r\n}\r\n```\r\n\r\n### Execution\r\n\r\n```typescript\r\nawait consumer.executeWithFeedback(\r\n  agent: AgentInfo,\r\n  request: ExecuteRequest\r\n): Promise<ExecuteResponse>\r\n```\r\n\r\n**ExecuteRequest:**\r\n```typescript\r\ninterface ExecuteRequest {\r\n  task: string;\r\n  params?: Record<string, any>;\r\n}\r\n```\r\n\r\n**ExecuteResponse:**\r\n```typescript\r\ninterface ExecuteResponse {\r\n  success: boolean;\r\n  data?: any;\r\n  error?: string;\r\n}\r\n```\r\n\r\n**Multi-Agent Execution:**\r\n```typescript\r\nawait consumer.executeMultipleWithFeedback(\r\n  agents: AgentInfo[],\r\n  request: ExecuteRequest,\r\n  context?: { userPrompt: string; analysis: Analysis }\r\n): Promise<ExecuteResponse[]>\r\n```\r\n\r\n> **💡 Tip:** Always use `executeWithFeedback()` or `executeMultipleWithFeedback()` instead of plain `execute()`. Feedback improves agent rankings in the registry over time.\r\n\r\n---\r\n\r\n## 🌍 Environment Variables\r\n\r\nCreate a `.env` file:\r\n\r\n```bash\r\n# Environment\r\nNODE_ENV=development  # or production\r\n\r\n# Registry URL (optional - auto-detected)\r\n# If unset:\r\n#   NODE_ENV=production -> https://automata.apptrixcloud.com\r\n#   otherwise          -> https://automata-dev.apptrixcloud.com\r\nREGISTRY_URL=https://automata-dev.apptrixcloud.com\r\n\r\n# LLM Configuration (REQUIRED)\r\nLLM_PROVIDER=openai          # openai, claude, gemini, deepseek, openrouter\r\nLLM_MODEL=gpt-4o-mini\r\nLLM_API_KEY=your-api-key\r\n\r\n# Client ID (optional - for stable caller_id)\r\nCLIENT_ID=my-consumer-app\r\n```\r\n\r\n---\r\n\r\n## 🎓 Supported LLM Providers\r\n\r\n### OpenAI\r\n- `gpt-4.1`, `gpt-4o`, `gpt-4.1-mini`, `gpt-4o-mini`, `o3-mini`\r\n\r\n### Claude (Anthropic)\r\n- `claude-3-5-sonnet-20241022`, `claude-3-5-haiku-20241022`, `claude-3-opus-20240229`\r\n\r\n### Gemini (Google)\r\n- `gemini-2.0-flash-exp`, `gemini-1.5-pro`, `gemini-1.5-flash`\r\n\r\n### DeepSeek\r\n- `deepseek-chat`, `deepseek-coder`\r\n\r\n### OpenRouter\r\n- `anthropic/claude-3.5-sonnet`, `google/gemini-1.5-pro`, `openai/gpt-4o`\r\n\r\n---\r\n\r\n## 💡 Best Practices\r\n\r\n1. **Use LLM-powered search**: Let `analyzePrompt()` extract intents, categories, and keywords from natural language\r\n2. **Always send feedback**: Use `executeWithFeedback()` to improve agent rankings\r\n3. **Validate semantically**: Use `validateAgentRelevance()` to filter false positives\r\n4. **Provide context for schemas**: When calling `executeMultipleWithFeedback`, include `{ userPrompt, analysis }` so the SDK can map provider schemas\r\n5. **Limit results**: Set a reasonable `limit` in search (10-20) to avoid overload\r\n6. **Handle pending agents**: Check `consumer.getPendingAgents()` to retry agents that had missing fields\r\n7. **Be specific with location**: Use `City,State,Country` format for best results\r\n8. **Let LLM handle language**: Don't restrict user input - the LLM adapts to any language\r\n\r\n---\r\n\r\n## 🧠 Memory & Context Management\r\n\r\nThe Consumer SDK includes built-in conversation memory for maintaining context across multiple requests:\r\n\r\n### Memory Methods\r\n\r\n```typescript\r\n// Add a conversation to memory\r\nconsumer.addToMemory({\r\n  userRequest: \"Find hotels in Miami\",\r\n  intent: \"travel.hotel.search\",\r\n  timestamp: new Date(),\r\n  agentResponses: [...],\r\n  interpretation: \"I found 3 hotels...\"\r\n});\r\n\r\n// Get recent context (last N conversations)\r\nconst context = consumer.getRecentContext(3);\r\n\r\n// Get all memory\r\nconst allMemory = consumer.getMemory();\r\n\r\n// Clear memory\r\nconsumer.clearMemory();\r\n```\r\n\r\n### Pending Agents\r\n\r\nTrack agents that couldn't be executed due to missing required fields:\r\n\r\n```typescript\r\n// Get list of pending agents with missing fields\r\nconst pending = consumer.getPendingAgents();\r\n\r\n// Returns:\r\n[\r\n  {\r\n    agentId: 'agent:hotel:miami',\r\n    agentName: 'Miami Hotels',\r\n    endpoint: 'https://...',\r\n    executionKey: 'jwt...',\r\n    missingFields: ['checkIn', 'checkOut'],\r\n    lastAttempt: Date\r\n  }\r\n]\r\n\r\n// Resolve a pending agent after providing missing data\r\nconsumer.resolvePendingAgent('agent:hotel:miami');\r\n```\r\n\r\n### Agent Caching\r\n\r\nThe SDK automatically caches searched agents for quick retrieval:\r\n\r\n```typescript\r\n// Agents are cached automatically after search\r\nconst agents = await consumer.search({...});\r\nconsumer.cacheAgents(agents);  // Automatic\r\n\r\n// Memory and cache are cleared together\r\nconsumer.clearMemory();  // Also clears cache and pending agents\r\n```\r\n\r\n---\r\n\r\n## 🛠️ Development\r\n\r\n```bash\r\n# Install dependencies\r\nnpm install\r\n\r\n# Build\r\nnpm run build\r\n\r\n# Run example\r\nnpm run example\r\n\r\n# Watch mode\r\nnpm run dev\r\n```\r\n\r\n---\r\n\r\n## 📖 Related Documentation\r\n\r\n- **Provider SDK**: Create agents that appear in the registry → [sdk-agent-provider](../sdk-agent-provider)\r\n- **Registry Central**: Run your own registry → [registry-central](../registry-central)\r\n\r\n---\r\n\r\n## License\r\n\r\nMIT\r\n","readmeFilename":"README.md"}