@xano/developer-mcp 1.0.20 → 1.0.22

package/dist/xanoscript_docs_auto/agents.md

@@ -0,0 +1,446 @@
+---
+applyTo: "agents/**/*.xs"
+---
+
+# AI Agents
+
+AI agent configuration with LLM providers, tools, and conversation management.
+
+## Quick Reference
+
+```xs
+agent "<name>" {
+  model = "openai:gpt-4"
+  system_prompt = "You are a helpful assistant."
+  tools = [search, calculator]
+  max_tokens = 1000
+  temperature = 0.7
+}
+```
+
+---
+
+## Agent Definition
+
+### Basic Agent
+
+```xs
+agent "customer_support" {
+  model = "openai:gpt-4"
+  system_prompt = "You are a customer support agent. Help users with their questions about our products and services."
+  max_tokens = 500
+  temperature = 0.7
+}
+```
+
+### Agent with Tools
+
+```xs
+agent "data_analyst" {
+  model = "openai:gpt-4"
+  system_prompt = "You are a data analyst. Use the available tools to query data and provide insights."
+  tools = [query_database, generate_chart, export_data]
+  max_tokens = 1000
+  temperature = 0.5
+}
+```
+
+---
+
+## Model Configuration
+
+### OpenAI Models
+
+```xs
+model = "openai:gpt-4"
+model = "openai:gpt-4-turbo"
+model = "openai:gpt-3.5-turbo"
+```
+
+### Anthropic Models
+
+```xs
+model = "anthropic:claude-3-opus"
+model = "anthropic:claude-3-sonnet"
+model = "anthropic:claude-3-haiku"
+```
+
+### Custom Provider
+
+```xs
+model = "custom:my-model"
+api_base = "https://my-llm-api.com/v1"
+api_key = $env.CUSTOM_API_KEY
+```
+
+---
+
+## Agent Parameters
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `model` | LLM model identifier | Required |
+| `system_prompt` | Instructions for the agent | Required |
+| `tools` | Available tools | `[]` |
+| `max_tokens` | Maximum response tokens | `500` |
+| `temperature` | Creativity (0-1) | `0.7` |
+| `top_p` | Nucleus sampling | `1` |
+| `stop` | Stop sequences | `[]` |
+
+---
+
+## System Prompts
+
+### Simple Prompt
+
+```xs
+agent "assistant" {
+  model = "openai:gpt-4"
+  system_prompt = "You are a helpful assistant."
+}
+```
+
+### Detailed Prompt
+
+```xs
+agent "product_expert" {
+  model = "openai:gpt-4"
+  system_prompt = """
+You are a product expert for our e-commerce platform.
+
+Your responsibilities:
+- Answer questions about products
+- Provide recommendations based on user needs
+- Help with order-related queries
+
+Guidelines:
+- Be friendly and professional
+- If you don't know something, say so
+- Always verify information using available tools
+"""
+}
+```
+
+### Dynamic Prompt
+
+```xs
+agent "personalized_assistant" {
+  model = "openai:gpt-4"
+  system_prompt = "You are a personal assistant for " ~ $user.name ~ ". Their preferences are: " ~ $user.preferences|json_encode
+}
+```
+
+---
+
+## Running Agents
+
+### Basic Execution
+
+```xs
+ai.agent.run {
+  agent = "customer_support"
+  message = $input.user_message
+} as $response
+```
+
+### With Conversation History
+
+```xs
+ai.agent.run {
+  agent = "customer_support"
+  message = $input.user_message
+  history = $conversation.messages
+} as $response
+```
+
+### With Context
+
+```xs
+ai.agent.run {
+  agent = "product_expert"
+  message = $input.question
+  context = {
+    user_id: $auth.id,
+    cart_items: $cart.items,
+    recent_orders: $recent_orders
+  }
+} as $response
+```
+
+---
+
+## Conversation Management
+
+### Store Conversation
+
+```xs
+// Add user message
+db.add message {
+  data = {
+    conversation_id: $input.conversation_id,
+    role: "user",
+    content: $input.message,
+    created_at: now
+  }
+}
+
+// Get agent response
+ai.agent.run {
+  agent = "assistant"
+  message = $input.message
+  history = $previous_messages
+} as $response
+
+// Store agent response
+db.add message {
+  data = {
+    conversation_id: $input.conversation_id,
+    role: "assistant",
+    content: $response.content,
+    created_at: now
+  }
+}
+```
+
+### Load History
+
+```xs
+db.query message {
+  where = $db.message.conversation_id == $input.conversation_id
+  order_by = {field: "created_at", direction: "asc"}
+  return = {type: "list", paging: {per_page: 50}}
+} as $history
+
+var $formatted_history {
+  value = $history|map:{role: $$.role, content: $$.content}
+}
+```
+
+---
+
+## Tools Integration
+
+### Linking Tools to Agents
+
+```xs
+agent "smart_assistant" {
+  model = "openai:gpt-4"
+  system_prompt = "Use tools to help users."
+  tools = [
+    search_products,
+    check_inventory,
+    create_order,
+    get_order_status
+  ]
+}
+```
+
+### Tool Execution
+
+When the agent calls a tool, the response includes tool calls that Xano automatically executes:
+
+```xs
+ai.agent.run {
+  agent = "smart_assistant"
+  message = "Check if iPhone 15 is in stock"
+} as $response
+
+// $response.content contains the agent's response
+// Tool calls are automatically executed
+```
+
+---
+
+## Agent Triggers
+
+Handle events from agent interactions:
+
+```xs
+agent_trigger "on_tool_call" {
+  agent = "smart_assistant"
+  event = "tool_call"
+
+  stack {
+    // Log tool usage
+    db.add agent_log {
+      data = {
+        agent: $trigger.agent,
+        tool: $trigger.tool_name,
+        input: $trigger.tool_input,
+        created_at: now
+      }
+    }
+  }
+}
+```
+
+---
+
+## Error Handling
+
+```xs
+try_catch {
+  try {
+    ai.agent.run {
+      agent = "assistant"
+      message = $input.message
+      timeout = 30000
+    } as $response
+  }
+  catch {
+    var $response {
+      value = {
+        content: "I'm sorry, I encountered an error. Please try again.",
+        error: true
+      }
+    }
+  }
+}
+```
+
+---
+
+## Streaming Responses
+
+For real-time responses:
+
+```xs
+query "chat" verb=POST {
+  stack {
+    api.stream {
+      content_type = "text/event-stream"
+      run {
+        ai.agent.run {
+          agent = "assistant"
+          message = $input.message
+          stream = true
+          on_token {
+            api.stream.write {
+              data = "data: " ~ $this.token ~ "\n\n"
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+---
+
+## Example: Customer Service Agent
+
+```xs
+agent "customer_service" {
+  model = "openai:gpt-4"
+  system_prompt = """
+You are a customer service agent for TechStore.
+
+Available actions:
+- Look up orders by order number or email
+- Check product availability
+- Process returns and refunds
+- Answer questions about products
+
+Guidelines:
+- Always verify customer identity before sharing order details
+- Be polite and professional
+- Escalate complex issues to human support
+
+Use the provided tools to assist customers.
+"""
+  tools = [
+    lookup_order,
+    check_inventory,
+    process_return,
+    search_products,
+    create_ticket
+  ]
+  max_tokens = 1000
+  temperature = 0.5
+}
+
+// Tool definitions
+tool "lookup_order" {
+  description = "Look up an order by order number or customer email"
+  input {
+    text? order_number
+    email? customer_email
+  }
+  stack {
+    db.query order {
+      where = $db.order.order_number ==? $input.order_number
+            || $db.order.customer_email ==? $input.customer_email
+    } as $orders
+  }
+  response = $orders
+}
+
+tool "check_inventory" {
+  description = "Check if a product is in stock"
+  input {
+    text product_name
+  }
+  stack {
+    db.query product {
+      where = $db.product.name ilike ("%" ~ $input.product_name ~ "%")
+    } as $products
+  }
+  response = $products|map:{name: $$.name, stock: $$.stock, available: $$.stock > 0}
+}
+```
+
+---
+
+## Example: Data Analysis Agent
+
+```xs
+agent "data_analyst" {
+  model = "openai:gpt-4"
+  system_prompt = """
+You are a data analyst. Help users understand their data by:
+- Running queries to find insights
+- Generating summary statistics
+- Creating visualizations
+- Explaining trends and patterns
+
+Always explain your analysis in plain language.
+"""
+  tools = [
+    run_query,
+    calculate_stats,
+    generate_chart
+  ]
+  max_tokens = 2000
+  temperature = 0.3
+}
+```
+
+---
+
+## Best Practices
+
+### Clear System Prompts
+
+- Define the agent's role clearly
+- List available capabilities
+- Specify guidelines and constraints
+- Provide examples if helpful
+
+### Appropriate Tool Selection
+
+- Only include relevant tools
+- Use descriptive tool names
+- Document tool parameters well
+
+### Handle Edge Cases
+
+- Set reasonable timeouts
+- Catch and handle errors
+- Provide fallback responses
+
+### Security
+
+- Validate tool inputs
+- Limit agent capabilities
+- Log agent actions for auditing