# AIAgentProxy State

The `AIAgentProxyState` is used to define an AI Agent Proxy state within a serverless workflow. This state facilitates interaction with an AI agent, allowing for user messages, system prompts, and agent outcomes to be managed within a workflow.

### AIAgentProxyState

The `AIAgentProxyState` is a specialized state in a serverless workflow designed to integrate AI agents developed by any AI framework. The state defines the agent's configuration, including the integration details, possible outcomes, and other properties.

<table data-header-hidden><thead><tr><th width="174"></th><th></th><th width="116"></th><th></th></tr></thead><tbody><tr><td><strong>Parameter</strong></td><td><strong>Description</strong></td><td><strong>Type</strong></td><td><strong>Required</strong></td></tr><tr><td>agentName</td><td>The name of the agent.</td><td>string</td><td>yes</td></tr><tr><td>systemMessage</td><td>The system message used to construct the LLM prompt.</td><td>string</td><td>no</td></tr><tr><td>userMessage</td><td>The user message.</td><td>string</td><td>yes</td></tr><tr><td>memoryId</td><td>The memory ID to store the agent history. If not specified, the workflow process instance scope is used.</td><td>string</td><td>no</td></tr><tr><td><a href="#onagentoutcome">agentOutcomes</a></td><td>Define list of agent outcomes. Each outcome is described by the <a href="#onagentoutcome">OnAgentOutcome</a> schema.</td><td>array</td><td>yes</td></tr><tr><td><a href="#agentproxyexecution">execution</a></td><td>Agent proxy execution described by the AgentProxyExecution schema.</td><td>object</td><td>yes</td></tr><tr><td><a href="https://docs.a4b.vn/xflow/3.-core-concepts/workflow-data-handling#state-data-filters">dataFilter</a></td><td>Filter to apply to the state data.</td><td>string</td><td>no</td></tr></tbody></table>

### OnAgentOutcome

The `OnAgentOutcome` object defines the actions to be performed based on the outcome of the AI agent. The actions are executed if the outcome matches the specified conditions.

<table data-header-hidden><thead><tr><th width="137"></th><th width="274"></th><th width="137"></th><th></th></tr></thead><tbody><tr><td><strong>Field</strong></td><td><strong>Description</strong></td><td><strong>Type</strong></td><td><strong>Required</strong></td></tr><tr><td>condition</td><td>Expression, if defined, must evaluate to true for this outcome to be matched. If false, the outcome is disregarded.</td><td>string</td><td>no</td></tr><tr><td>finish</td><td>If true, the agent will finish after this action is executed. If false, the agent will continue to process.</td><td>boolean</td><td>no</td></tr><tr><td><a href="https://docs.a4b.vn/xflow/3.-core-concepts/workflow-data-handling#event-data-filters">dataFilter</a></td><td>Event data filter described by the <a href="https://docs.a4b.vn/xflow/3.-core-concepts/workflow-data-handling#event-data-filters">EventDataFilter</a> schema.</td><td>object</td><td>no</td></tr><tr><td><a href="https://github.com/serverlessworkflow/specification/blob/0.9.x/specification.md#Transitions">transition</a></td><td>The outgoing transition when the outcome is selected, if not defined the default transition will be used.</td><td>object</td><td>no</td></tr></tbody></table>

### AgentProxyExecution

The `AgentProxyExecution` object specifies how the AI Agent are to be invoked by the AI Agent Proxy. The function will be executed and provided with 3 arguments: `workflowId`, `agentConfig`, and `agentContext`. (See [AI Agent Proxy Integration](/xflow/developer-guide/ai-agent-development/ai-agent-proxy/ai-agents-integration.md))

<table data-header-hidden><thead><tr><th width="149"></th><th width="298"></th><th></th><th></th></tr></thead><tbody><tr><td><strong>Field</strong></td><td><strong>Description</strong></td><td><strong>Type</strong></td><td><strong>Required</strong></td></tr><tr><td><a href="https://github.com/serverlessworkflow/specification/blob/0.9.x/specification.md#functionref-definition">functionRef</a></td><td>References a reusable function definition to be invoked</td><td>object</td><td>yes</td></tr></tbody></table>

**Example:**

<table><thead><tr><th>YAML</th><th data-hidden>JSON</th></tr></thead><tbody><tr><td><pre class="language-yaml" data-line-numbers><code class="lang-yaml">states:
  - name: RagAgentProxy
    agentName: RagAgentProxy
    type: aiagentproxy
    systemMessage: You are a helpful assistant
    userMessage: '${ .request.question }'
    execution:
      functionRef:
        refName: "ExecuteRagAgentProxy"
    agentOutcomes:
    - condition: '${ true }'
      finish: true
      transition: InformRagAgentProxyResult
  - name: InformRagAgentProxyResult
    agentName: InformRagAgentProxyResult
    type: userproxyagent
    agentRole: relay
    userMessage: '${ .request.question }'
    relayMessage:
      text: ${ ._ai_agent_state.RagAgentProxy.agentOutcome.finish.output.message }
      mediaExp: ${ ._ai_agent_state.RagAgentProxy.agentOutcome.finish.output.images }
    output: |-
      {
          "type": "object",
          "properties": {
              "answer": {
                  "type": "string"
              }
          },
          "required": ["answer"]
      }
    agentOutcomes:
    - condition: '${ true }'
      finish: true
      transition: Finish
functions:
  - name: ExecuteRagAgentProxy
    type: custom
    operation: ExecuteQueryAction
    metadata:
      libraryQueryName: post.rag_agent_proxy
      libraryQueryRecordId: latest
      params: '["workflowId", "agentConfig", "agentContext"]'
</code></pre></td><td><pre class="language-json" data-line-numbers><code class="lang-json">{
    "states": [
        {
            "name": "RagAgentProxy",
            "agentName": "RagAgentProxy",
            "type": "aiagent",
            "agentType": "agent_proxy",
            "aiModel": "gpt-4o",
            "systemMessage": "You are a helpful assistant",
            "userMessage": "${ .request.question }",
            "agentProxy": {
                "functionRef": {
                    "refName": "ExecuteRagAgentProxy"
                }
            },
            "tools": [],
            "agentOutcomes": [
                {
                    "condition": "${ true }",
                    "finish": true,
                    "transition": "InformRagAgentProxyResult"
                }
            ]
        },
        {
            "name": "InformRagAgentProxyResult",
            "agentName": "InformRagAgentProxyResult",
            "type": "userproxyagent",
            "agentRole": "relay",
            "userMessage": "${ .request.question }",
            "conversationId": "${ .request.userChannelContext.conversationId }",
            "userChannelContext": "${ .request.userChannelContext }",
            "userContext": "${ .request.userContext }",
            "relayMessage": {
                "text": "${ ._ai_agent_state.RagAgentProxy.agentOutcome.finish.output.message }",
                "mediaExp": "${ ._ai_agent_state.RagAgentProxy.agentOutcome.finish.output.images }"
            },
            "output": "{\n    \"type\": \"object\",\n    \"properties\": {\n        \"answer\": {\n            \"type\": \"string\"\n        }\n    },\n    \"required\": [\"answer\"]\n}",
            "agentOutcomes": [
                {
                    "condition": "${ true }",
                    "finish": true,
                    "transition": "Finish"
                }
            ]
        }
    ]
}
</code></pre></td></tr></tbody></table>

***

This document provides a detailed view of the `AIAgentProxyState` state and its related objects, including comprehensive schema definitions, required fields, and descriptions for each attribute within the `AIAgentProxyState` and associated schemas. This specification ensures clarity and completeness for integrating AI agents within serverless workflows.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.a4b.vn/xflow/developer-guide/workflow-states-reference/aiagentproxy-state.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.