|
| 1 | +--- |
| 2 | +name: ai-agent-design |
| 3 | +description: > |
| 4 | + Design ObjectStack AI agents, skills, tools, and RAG pipelines. |
| 5 | + Use when configuring autonomous agents, defining agent skills and tool sets, |
| 6 | + setting up retrieval-augmented generation, or integrating LLM models |
| 7 | + in an ObjectStack project. |
| 8 | +license: Apache-2.0 |
| 9 | +compatibility: Requires @objectstack/spec Zod schemas (v4+) |
| 10 | +metadata: |
| 11 | + author: objectstack-ai |
| 12 | + version: "1.0" |
| 13 | + domain: ai |
| 14 | + tags: agent, skill, tool, rag, llm |
| 15 | +--- |
| 16 | + |
| 17 | +# AI Agent Design — ObjectStack AI Protocol |
| 18 | + |
| 19 | +Expert instructions for designing AI-powered agents, skills, tools, and RAG |
| 20 | +pipelines using the ObjectStack specification. This skill covers the |
| 21 | +Agent → Skill → Tool three-tier architecture aligned with Salesforce |
| 22 | +Agentforce, Microsoft Copilot Studio, and ServiceNow Now Assist patterns. |
| 23 | + |
| 24 | +--- |
| 25 | + |
| 26 | +## When to Use This Skill |
| 27 | + |
| 28 | +- You are creating an **AI agent** with a specific role and capabilities. |
| 29 | +- You need to define **skills** — bundles of related tools an agent can use. |
| 30 | +- You are configuring **tools** for data queries, actions, or integrations. |
| 31 | +- You want to set up a **RAG pipeline** for knowledge retrieval. |
| 32 | +- You are choosing and configuring **LLM models** for your agent. |
| 33 | + |
| 34 | +--- |
| 35 | + |
| 36 | +## Three-Tier Architecture |
| 37 | + |
| 38 | +``` |
| 39 | +Agent → Skill → Tool |
| 40 | + │ │ │ |
| 41 | + │ │ └─ Atomic operation (query, action, flow, API call) |
| 42 | + │ └─ Capability bundle with instructions & trigger phrases |
| 43 | + └─ Autonomous actor with role, instructions, and guardrails |
| 44 | +``` |
| 45 | + |
| 46 | +### Why Three Tiers? |
| 47 | + |
| 48 | +| Tier | Analogy | Reuse Level | |
| 49 | +|:-----|:--------|:------------| |
| 50 | +| **Agent** | Job role (e.g., "Help Desk Agent") | Per use-case | |
| 51 | +| **Skill** | Competency (e.g., "Case Management") | Across agents | |
| 52 | +| **Tool** | Specific operation (e.g., "create_record") | Across skills | |
| 53 | + |
| 54 | +> **Best practice:** Always model via Skills first. Direct tool assignment to |
| 55 | +> agents is supported but considered legacy. Skills provide better |
| 56 | +> discoverability, instruction scoping, and reuse. |
| 57 | +
|
| 58 | +--- |
| 59 | + |
| 60 | +## Agent Configuration |
| 61 | + |
| 62 | +### Required Properties |
| 63 | + |
| 64 | +| Property | Type | Description | |
| 65 | +|:---------|:-----|:------------| |
| 66 | +| `name` | `snake_case` | Unique agent identifier | |
| 67 | +| `label` | string | Human-readable name | |
| 68 | +| `role` | string | Agent's persona/role description | |
| 69 | +| `instructions` | string | System prompt — detailed behavioural guidance | |
| 70 | + |
| 71 | +### Important Optional Properties |
| 72 | + |
| 73 | +| Property | Purpose | |
| 74 | +|:---------|:--------| |
| 75 | +| `skills` | Array of skill names — **primary capability model** | |
| 76 | +| `tools` | Direct tool references — legacy fallback | |
| 77 | +| `model` | LLM model configuration | |
| 78 | +| `knowledge` | RAG knowledge sources | |
| 79 | +| `guardrails` | Safety constraints and topic restrictions | |
| 80 | +| `structuredOutput` | Output format (JSON schema, regex, etc.) | |
| 81 | +| `temperature` | LLM creativity level (0.0–2.0) | |
| 82 | +| `maxTokens` | Response token limit | |
| 83 | +| `active` | Enable/disable the agent | |
| 84 | + |
| 85 | +### Agent Example |
| 86 | + |
| 87 | +```typescript |
| 88 | +import { defineAgent } from '@objectstack/spec'; |
| 89 | + |
| 90 | +export default defineAgent({ |
| 91 | + name: 'support_tier_1', |
| 92 | + label: 'First Line Support', |
| 93 | + role: 'Help Desk Assistant for customer support cases', |
| 94 | + instructions: ` |
| 95 | + You are a friendly and professional help desk assistant. |
| 96 | + |
| 97 | + RULES: |
| 98 | + - Always greet the customer by name if available. |
| 99 | + - Search the knowledge base before creating a new case. |
| 100 | + - Escalate to a human agent if the issue is critical or security-related. |
| 101 | + - Never share internal system details with customers. |
| 102 | + - Respond in the customer's preferred language. |
| 103 | + `, |
| 104 | + skills: ['case_management', 'knowledge_search'], |
| 105 | + model: { |
| 106 | + provider: 'openai', |
| 107 | + model: 'gpt-4o', |
| 108 | + temperature: 0.3, |
| 109 | + }, |
| 110 | + guardrails: { |
| 111 | + blockedTopics: ['internal_pricing', 'employee_data'], |
| 112 | + maxTurns: 20, |
| 113 | + requireApprovalFor: ['delete_record', 'escalate'], |
| 114 | + }, |
| 115 | +}); |
| 116 | +``` |
| 117 | + |
| 118 | +--- |
| 119 | + |
| 120 | +## Skill Configuration |
| 121 | + |
| 122 | +A **Skill** is a named bundle of tools with dedicated instructions and |
| 123 | +trigger conditions. |
| 124 | + |
| 125 | +### Required Properties |
| 126 | + |
| 127 | +| Property | Type | Description | |
| 128 | +|:---------|:-----|:------------| |
| 129 | +| `name` | `snake_case` | Unique skill identifier (`/^[a-z_][a-z0-9_]*$/`) | |
| 130 | +| `label` | string | Human-readable name | |
| 131 | +| `tools` | `string[]` | Tool names this skill grants access to | |
| 132 | +| `active` | boolean | Is the skill enabled (default: `true`) | |
| 133 | + |
| 134 | +### Important Optional Properties |
| 135 | + |
| 136 | +| Property | Purpose | |
| 137 | +|:---------|:--------| |
| 138 | +| `description` | What the skill does — helps the agent decide when to use it | |
| 139 | +| `instructions` | LLM prompt guidance specific to this skill's context | |
| 140 | +| `triggerPhrases` | Natural language phrases that activate the skill | |
| 141 | +| `triggerConditions` | Programmatic activation rules | |
| 142 | +| `permissions` | Required permission profiles/roles | |
| 143 | + |
| 144 | +### Skill Example |
| 145 | + |
| 146 | +```typescript |
| 147 | +import { defineSkill } from '@objectstack/spec'; |
| 148 | + |
| 149 | +export default defineSkill({ |
| 150 | + name: 'case_management', |
| 151 | + label: 'Case Management', |
| 152 | + description: 'Create, update, query, and escalate support cases.', |
| 153 | + instructions: ` |
| 154 | + When managing cases: |
| 155 | + - Always check for duplicate cases before creating a new one. |
| 156 | + - Set priority based on customer tier: Enterprise → High, Pro → Medium, Free → Low. |
| 157 | + - Escalated cases must include a summary of actions already taken. |
| 158 | + `, |
| 159 | + tools: [ |
| 160 | + 'query_support_case', |
| 161 | + 'create_support_case', |
| 162 | + 'update_support_case', |
| 163 | + 'escalate_case', |
| 164 | + ], |
| 165 | + triggerPhrases: [ |
| 166 | + 'I need help with a case', |
| 167 | + 'Create a support ticket', |
| 168 | + 'What is the status of my case', |
| 169 | + 'Escalate this issue', |
| 170 | + ], |
| 171 | + triggerConditions: [ |
| 172 | + { field: 'object', operator: 'eq', value: 'support_case' }, |
| 173 | + ], |
| 174 | + permissions: ['support_agent', 'support_admin'], |
| 175 | + active: true, |
| 176 | +}); |
| 177 | +``` |
| 178 | + |
| 179 | +### Trigger Conditions |
| 180 | + |
| 181 | +| Operator | Meaning | |
| 182 | +|:---------|:--------| |
| 183 | +| `eq` | Equals | |
| 184 | +| `neq` | Not equals | |
| 185 | +| `in` | Value is in array | |
| 186 | +| `not_in` | Value is not in array | |
| 187 | +| `contains` | String contains substring | |
| 188 | + |
| 189 | +--- |
| 190 | + |
| 191 | +## Tool Configuration |
| 192 | + |
| 193 | +Tools are the atomic operations that skills expose to agents. |
| 194 | + |
| 195 | +### Tool Types |
| 196 | + |
| 197 | +| Type | Purpose | Example | |
| 198 | +|:-----|:--------|:--------| |
| 199 | +| `action` | Trigger a server-side action | "Close case", "Send email" | |
| 200 | +| `flow` | Launch a flow | "Reset password flow" | |
| 201 | +| `query` | Query ObjectStack records | "Get open cases for account" | |
| 202 | +| `vector_search` | Semantic search over embeddings | "Find similar articles" | |
| 203 | + |
| 204 | +### Tool Definition |
| 205 | + |
| 206 | +```typescript |
| 207 | +{ |
| 208 | + name: 'query_support_case', |
| 209 | + type: 'query', |
| 210 | + object: 'support_case', |
| 211 | + description: 'Search support cases by any combination of filters.', |
| 212 | + parameters: { |
| 213 | + status: { type: 'string', description: 'Filter by case status' }, |
| 214 | + account_id: { type: 'string', description: 'Filter by account ID' }, |
| 215 | + priority: { type: 'string', enum: ['low', 'medium', 'high', 'urgent'] }, |
| 216 | + }, |
| 217 | +} |
| 218 | +``` |
| 219 | + |
| 220 | +--- |
| 221 | + |
| 222 | +## RAG Pipeline Configuration |
| 223 | + |
| 224 | +Retrieval-Augmented Generation gives agents access to domain knowledge. |
| 225 | + |
| 226 | +### RAG Pipeline Structure |
| 227 | + |
| 228 | +```typescript |
| 229 | +{ |
| 230 | + name: 'support_knowledge', |
| 231 | + label: 'Support Knowledge Base', |
| 232 | + sources: [ |
| 233 | + { |
| 234 | + type: 'object', |
| 235 | + object: 'knowledge_article', |
| 236 | + fields: ['title', 'content', 'category'], |
| 237 | + filter: [{ field: 'published', operator: 'equals', value: true }], |
| 238 | + }, |
| 239 | + { |
| 240 | + type: 'document', |
| 241 | + path: 'docs/support-handbook.md', |
| 242 | + }, |
| 243 | + ], |
| 244 | + indexes: [ |
| 245 | + { |
| 246 | + name: 'article_embeddings', |
| 247 | + model: 'text-embedding-3-small', |
| 248 | + dimensions: 1536, |
| 249 | + distanceMetric: 'cosine', |
| 250 | + }, |
| 251 | + ], |
| 252 | + retrieval: { |
| 253 | + topK: 5, |
| 254 | + scoreThreshold: 0.75, |
| 255 | + reranker: 'cohere-rerank-v3', |
| 256 | + }, |
| 257 | +} |
| 258 | +``` |
| 259 | + |
| 260 | +### RAG Best Practices |
| 261 | + |
| 262 | +1. **Chunk documents appropriately.** 500–1000 tokens per chunk with 100-token |
| 263 | + overlap works well for most use cases. |
| 264 | +2. **Set a `scoreThreshold`** to filter low-relevance results. Start with `0.7` |
| 265 | + and tune. |
| 266 | +3. **Use a reranker** for better precision when the initial retrieval returns |
| 267 | + many candidates. |
| 268 | +4. **Filter by published/active status** to avoid surfacing draft or archived |
| 269 | + content. |
| 270 | +5. **Index only searchable fields** — do not index system fields or IDs. |
| 271 | + |
| 272 | +--- |
| 273 | + |
| 274 | +## Model Configuration |
| 275 | + |
| 276 | +### Supported Providers |
| 277 | + |
| 278 | +| Provider | Models | Use Case | |
| 279 | +|:---------|:-------|:---------| |
| 280 | +| `openai` | GPT-4o, GPT-4o-mini, o1, o3-mini | General purpose, reasoning | |
| 281 | +| `anthropic` | Claude Sonnet 4, Claude Haiku | Long context, safety | |
| 282 | +| `azure_openai` | Same as OpenAI, enterprise managed | Compliance, data residency | |
| 283 | +| `local` | Ollama, vLLM, llama.cpp | On-premise, air-gapped | |
| 284 | + |
| 285 | +### Model Selection Guidelines |
| 286 | + |
| 287 | +| Scenario | Recommended | |
| 288 | +|:---------|:------------| |
| 289 | +| Complex reasoning, multi-step planning | GPT-4o / Claude Sonnet 4 | |
| 290 | +| High-volume, low-latency | GPT-4o-mini / Claude Haiku | |
| 291 | +| Sensitive data, on-premise | Local models via Ollama | |
| 292 | +| Structured data extraction | Any model + `structuredOutput` config | |
| 293 | + |
| 294 | +### Temperature Guidelines |
| 295 | + |
| 296 | +| Value | Use Case | |
| 297 | +|:------|:---------| |
| 298 | +| `0.0–0.3` | Factual Q&A, data extraction, code generation | |
| 299 | +| `0.3–0.7` | Conversational agents, customer support | |
| 300 | +| `0.7–1.0` | Creative writing, brainstorming | |
| 301 | +| `> 1.0` | Experimental / highly creative (use with caution) | |
| 302 | + |
| 303 | +--- |
| 304 | + |
| 305 | +## Structured Output |
| 306 | + |
| 307 | +Force the agent to respond in a specific format: |
| 308 | + |
| 309 | +```typescript |
| 310 | +structuredOutput: { |
| 311 | + format: 'json_schema', |
| 312 | + schema: { |
| 313 | + type: 'object', |
| 314 | + properties: { |
| 315 | + summary: { type: 'string' }, |
| 316 | + priority: { type: 'string', enum: ['low', 'medium', 'high'] }, |
| 317 | + action_items: { type: 'array', items: { type: 'string' } }, |
| 318 | + }, |
| 319 | + required: ['summary', 'priority'], |
| 320 | + }, |
| 321 | + retry: { maxAttempts: 3 }, |
| 322 | +} |
| 323 | +``` |
| 324 | + |
| 325 | +--- |
| 326 | + |
| 327 | +## Common Pitfalls |
| 328 | + |
| 329 | +1. **Overly broad instructions.** Agents with vague instructions hallucinate |
| 330 | + more. Be specific about what the agent should and should not do. |
| 331 | +2. **Too many tools per skill.** Keep skills focused (3–8 tools). If a skill |
| 332 | + has 15+ tools, split it. |
| 333 | +3. **Missing guardrails.** Always define `blockedTopics` and |
| 334 | + `requireApprovalFor` destructive operations. |
| 335 | +4. **Ignoring tool descriptions.** The LLM uses tool `description` to decide |
| 336 | + when to call it. Poor descriptions = wrong tool selection. |
| 337 | +5. **Not testing trigger phrases.** Ambiguous trigger phrases cause skill |
| 338 | + conflicts. Test with edge-case inputs. |
| 339 | +6. **RAG without score threshold.** Without a threshold, low-relevance |
| 340 | + passages pollute the context window and degrade responses. |
| 341 | + |
| 342 | +--- |
| 343 | + |
| 344 | +## References |
| 345 | + |
| 346 | +- Zod source: `packages/spec/src/ai/agent.zod.ts` |
| 347 | +- Zod source: `packages/spec/src/ai/skill.zod.ts` |
| 348 | +- Zod source: `packages/spec/src/ai/tool.zod.ts` |
| 349 | +- Zod source: `packages/spec/src/ai/rag-pipeline.zod.ts` |
| 350 | +- Zod source: `packages/spec/src/ai/model-registry.zod.ts` |
| 351 | +- Documentation: `content/docs/references/ai/` |
0 commit comments