> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xano.com/llms.txt
> Use this file to discover all available pages before exploring further.

# XanoScript for AI Agents

> Learn how to define and configure AI Agents using XanoScript.

export const xanoscriptApiInputsDiagram = `
\`\`\`mermaid
flowchart TB
    A[Declaration] --> B[Input]
    B --> C[Stack]
    C --> D[Response]
    D --> E[Settings]
    style A fill:#cdeaff,stroke:#0077cc,stroke-width:2px
    style B fill:#f5f5f5,stroke:#ccc,stroke-width:1px
    style C fill:#f5f5f5,stroke:#ccc,stroke-width:1px
    style D fill:#f5f5f5,stroke:#ccc,stroke-width:1px
    style E fill:#f5f5f5,stroke:#ccc,stroke-width:1px
\`\`\`
`;

export function SideBySide({diagram, children}) {
  return <div style={{
    display: "flex",
    gap: "1rem",
    alignItems: "flex-start",
    flexWrap: "wrap"
  }}>
      <div style={{
    flex: "0 0 180px",
    minWidth: "150px"
  }}>
        <div>{mdx(diagram)}</div>
      </div>
      <div style={{
    flex: 1
  }}>
        {children}
      </div>
    </div>;
}

export const HoverImageCode = ({src, alt = "", width = "100%", maxWidth = "800px", className = "", defaultOpen = false, openOnHover = true, children}) => {
  const [open, setOpen] = useState(defaultOpen);
  const panelRef = useRef(null);
  const [maxHeight, setMaxHeight] = useState(0);
  useEffect(() => {
    if (panelRef.current) {
      setMaxHeight(open ? panelRef.current.scrollHeight : 0);
    }
  }, [open, children]);
  const handleMouseEnter = () => openOnHover && setOpen(true);
  const handleMouseLeave = () => openOnHover && setOpen(false);
  const handleClick = () => setOpen(s => !s);
  const handleImageClick = e => {
    e.stopPropagation();
    e.preventDefault();
    handleClick();
  };
  const prefersReducedMotion = typeof window !== "undefined" && window.matchMedia && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
  const transition = prefersReducedMotion ? "none" : "max-height 300ms ease, opacity 300ms ease, transform 300ms ease";
  return <div className={`border rounded-md overflow-hidden ${className}`} style={{
    width,
    maxWidth
  }} onMouseEnter={handleMouseEnter} onMouseLeave={handleMouseLeave}>
      {}
      <div role="button" tabIndex={0} aria-label="Toggle code" aria-expanded={open} style={{
    cursor: "pointer"
  }}>
        <img src={src} alt={alt} onClickCapture={e => {
    e.stopPropagation();
    e.preventDefault();
    handleClick();
  }} style={{
    display: "block",
    width: "100%",
    height: "auto"
  }} />
      </div>

      {}
      <div className="not-prose" ref={panelRef} style={{
    overflow: "hidden",
    maxHeight: `${maxHeight}px`,
    opacity: open ? 1 : 0,
    transform: open ? "translateY(0)" : "translateY(-6px)",
    transition
  }}>
        <div style={{
    padding: "0.75rem"
  }}>{children}</div>
      </div>
    </div>;
};

## Introduction

AI Agents in Xano allow you to define intelligent, autonomous workflows powered by models like Gemini, OpenAI, or Claude, directly in XanoScript.

## Anatomy

Every XanoScript Agent follows a predictable structure.

Here’s a quick visual overview of its main building blocks — from **declaration** at the top to **tools** at the bottom.<br /><br />It's a little different from other primitives, because the settings are defined in the `llm` block, instead of a separate settings block.<br /><br />You can find more detail about each section by continuing below.

```mermaid theme={null}
flowchart LR
    A[Declaration] --> B[LLM] --> C[Tools]
    style A fill:#f5f5f5,stroke:#ccc,stroke-width:1px
    style B fill:#f5f5f5,stroke:#ccc,stroke-width:1px
    style C fill:#f5f5f5,stroke:#ccc,stroke-width:1px
```

## Section 1: Declaration

Every Agent starts with a **declarative header** that specifies its type, name, and description.

<div style={{ display: "flex", gap: "1rem", alignItems: "flex-start", flexWrap: "wrap" }}>
  <div className="stickyDiagram">
    ```mermaid theme={null}
    flowchart TB
    A[Declaration] --> B[LLM] --> C[Tools]
    style A fill:#cdeaff,stroke:#0077cc,stroke-width:2px
    style B fill:#f5f5f5,stroke:#ccc,stroke-width:1px
    style C fill:#f5f5f5,stroke:#ccc,stroke-width:1px
    ```
  </div>

  <div style={{ flex: 1 }}>
    ```java XanoScript lines icon="code" theme={null}
    // This agent answers the user's question to the best of its ability.
    agent "Answer a Question" {
      canonical = "Zwt3YW_3"
      tags = ["tag1", "tag2"]
    }
    ```

    | Element       | Required | Description                                                                      |
    | ------------- | -------- | -------------------------------------------------------------------------------- |
    | `agent`       | ✅        | Declares an Agent primitive and its name.                                        |
    | `description` | no       | A short summary of the agent. May also appear as a “//” comment above the block. |
    | `canonical`   | no       | The canonical ID for this Agent.                                                 |
    | `tags`        | no       | An array of strings used to categorize or filter Agents.                         |
  </div>
</div>

***

## Section 2: LLM

The `llm` block defines how your Agent interacts with its underlying AI model. All standard model configuration options available in the UI are represented here.

These are a little different from other primitives, because the settings available can change based on the model chosen.

<div style={{ display: "flex", gap: "1rem", alignItems: "flex-start", flexWrap: "wrap" }}>
  <div className="stickyDiagram">
    ```mermaid theme={null}
    flowchart TB
    A[Declaration] --> B[LLM] --> C[Tools]
    style B fill:#cdeaff,stroke:#0077cc,stroke-width:2px
    style A fill:#f5f5f5,stroke:#ccc,stroke-width:1px
    style C fill:#f5f5f5,stroke:#ccc,stroke-width:1px
    ```
  </div>

  <div style={{ flex: 1 }}>
    ```java XanoScript lines icon="code" theme={null}
    llm = {
      type         : "google-genai"
      system_prompt: "You are a helpful AI Agent that tries to answer the user's query using the best possible information. You are also required to log each interaction using the logging tool."
      max_steps    : 5
      prompt       : "Here is the user's query: {{ $args.query }}"
      ...
    ```

    | Element         | Required | Description                                                                             |
    | --------------- | -------- | --------------------------------------------------------------------------------------- |
    | `type`          | ✅        | The model host provider. Supported: `openai`, `anthropic`, `google-genai`, `xano-free`. |
    | `system_prompt` | no       | Core instructions defining the Agent’s role and behavior.                               |
    | `max_steps`     | no       | How many steps (tool calls) the Agent can take before stopping.                         |
    | `prompt`        | no       | Additional context or message prompt. Use `{{ $args.property }}` for dynamic data.      |
    | `api_key`       | no       | API key for the chosen model provider.                                                  |
    | `model`         | no       | Specific model to use.                                                                  |

    ### Xano Free Model (Gemini)

    These settings are specific to the Xano Free Model (Gemini).

    ```java XanoScript lines icon="code" theme={null}
      temperature     : 1
      search_grounding: false
      thinking_tokens : 0
      include_thoughts: false
    ```

    | Element            | Required | Description                                                |
    | ------------------ | -------- | ---------------------------------------------------------- |
    | `temperature`      | no       | Controls randomness of output. Lower = more deterministic. |
    | `search_grounding` | no       | For Gemini, whether to enable Google Search grounding.     |
    | `thinking_tokens`  | no       | For reasoning models, sets thinking budget.                |
    | `include_thoughts` | no       | Whether to include reasoning traces in the response.       |

    ### Anthropic (Claude)

    ```java XanoScript lines icon="code" theme={null}
      api_key      : "abc123"
      model        : "claude-4-sonnet-20250514"
      temperature  : 1
      reasoning    : true
    ```

    | Element       | Required | Description                                                |
    | ------------- | -------- | ---------------------------------------------------------- |
    | `api_key`     | ✅        | API key for the chosen model provider.                     |
    | `model`       | ✅        | Specific model to use.                                     |
    | `temperature` | no       | Controls randomness of output. Lower = more deterministic. |
    | `reasoning`   | no       | Whether to include reasoning traces in the response.       |

    ### Google Generative AI (Gemini)

    ```java XanoScript lines icon="code" theme={null}
      api_key         : "abc123"
      model           : "gemini-2.5-flash"
      temperature     : 1
      search_grounding: false
      thinking_tokens : 0
      include_thoughts: false
    ```

    | Element            | Required | Description                                                |
    | ------------------ | -------- | ---------------------------------------------------------- |
    | `api_key`          | ✅        | API key for the chosen model provider.                     |
    | `model`            | ✅        | Specific model to use.                                     |
    | `temperature`      | no       | Controls randomness of output. Lower = more deterministic. |
    | `search_grounding` | no       | For Gemini, whether to enable Google Search grounding.     |
    | `thinking_tokens`  | no       | For reasoning models, sets thinking budget.                |
    | `include_thoughts` | no       | Whether to include reasoning traces in the response.       |

    ### OpenAI

    OpenAI settings are similar to the other models, but also includes some additional advanced settings.

    #### OpenAI Settings

    ```java XanoScript lines icon="code" theme={null}
      api_key         : "abc123"
      model           : "gpt-5-mini"
      temperature     : 1
      reasoning_effort: ""
    ```

    | Element            | Required | Description                                                                             |
    | ------------------ | -------- | --------------------------------------------------------------------------------------- |
    | `api_key`          | ✅        | API key for the chosen model provider.                                                  |
    | `model`            | ✅        | Specific model to use.                                                                  |
    | `temperature`      | no       | Controls randomness of output. Lower = more deterministic.                              |
    | `reasoning_effort` | no       | For reasoning models, sets how much effort the model spends thinking during generation. |

    #### OpenAI Advanced Settings

    ```java XanoScript lines icon="code" theme={null}
      organization    : ""
      project         : ""
      compatibility   : "strict"
    ```

    | Element         | Required | Description                     |
    | --------------- | -------- | ------------------------------- |
    | `organization`  | no       | The organization to use.        |
    | `project`       | no       | The project to use.             |
    | `compatibility` | no       | The compatibility level to use. |
  </div>
</div>

***

## Section 3: Tools

The `tools` block defines the tools that an Agent can use. Tools are functions that an Agent can call as part of its steps to resolve the task at hand.

<div style={{ display: "flex", gap: "1rem", alignItems: "flex-start", flexWrap: "wrap" }}>
  <div className="stickyDiagram">
    ```mermaid theme={null}
    flowchart TB
        A[Declaration] --> B[LLM] --> C[Tools]
        style C fill:#cdeaff,stroke:#0077cc,stroke-width:2px
        style A fill:#f5f5f5,stroke:#ccc,stroke-width:1px
        style B fill:#f5f5f5,stroke:#ccc,stroke-width:1px
    ```
  </div>

  <div style={{ flex: 1 }}>
    ```java XanoScript lines icon="code" theme={null}
    tools = [
      {name: "Get_User_Info"}
      {name: "Create_Support_Ticket"}
    ]
    ```

    | Element                                                     | Required | Description                       |
    | ----------------------------------------------------------- | -------- | --------------------------------- |
    | `tools[]`                                                   | ✅        | The tools that the Agent can use. |
    |       <Icon icon="arrow-turn-down-right" size={16} />`name` | ✅        | The name of the tool.             |
  </div>
</div>

***

## Full Example

Below is a more complete Agent definition that combines multiple settings:

```java XanoScript lines icon="code" theme={null}
// Handles customer inquiries and support requests automatically.
agent "Customer Support Agent" {
  canonical   = "SUPPORT_AGENT_001"
  tags        = ["support", "customer-service"]

  llm = {
    type            : "anthropic"
    system_prompt   : "You are a helpful Customer Support Agent that resolves issues efficiently..."
    max_steps       : 8
    prompt          : "Customer inquiry: {{ $args.customer_message }}"
    api_key         : "{{ $env.ANTHROPIC_KEY }}"
    model           : "claude-3-7-sonnet-latest"
    temperature     : 0.3
    send_reasoning  : true
    thinking        : {
      type          : "enabled",
      budget_tokens : 10000
    }
  }

  tools = [
    { name: "Get_User_Info" },
    { name: "Update_User_Info" },
    { name: "Create_Ticket" }
  ]
}
```

***

## What's Next

Now that you understand how to define Agents in XanoScript, here are a few great next steps:

<Card title="Explore the function reference" icon="function" horizontal href="/xanoscript/function-reference">
  Learn about the built-in functions available in the stack to start writing more complex logic.
</Card>

<Card title="Try it out in VS Code" icon="https://mintcdn.com/xano-997cb9ee/aZQYcxhIvSDTNEim/images/icons/vscode.svg?fit=max&auto=format&n=aZQYcxhIvSDTNEim&q=85&s=bb6c91058fcbe6ee28fcda04e03de2e6" horizontal href="/xanoscript/vs-code" width="100" height="100" data-path="images/icons/vscode.svg">
  Use the XanoScript VS Code extension with Copilot to write XanoScript in your favorite IDE.
</Card>

<Card title="Learn about AI Tools" icon="cube" horizontal href="/xanoscript/ai-tools">
  AI Tools are used to define the actions that an Agent can take.
</Card>