Proxy Agent
Overview
The Proxy Agent acts as a proxy to delegate AI agent execution to external systems or services. This allows for distributed agent execution where the actual AI processing happens on remote systems while maintaining the same interface as local AI agents.
Configuration Details
name
The unique name of the AI agent proxy within the workflow.
String
Yes
-
start
Indicates if this is the starting agent of the workflow.
Boolean
No
false
transition
Defines the transition to the next flow node after this proxy completes. See TransitionDef
Object
No
-
answerAfterFinish
Whether the agent should provide an answer message after finishing execution.
Boolean
No
false
answerMessage
Custom message to display when the agent finishes (if answerAfterFinish is true).
String
No
-
systemMessage
System message that defines the agent's role and behavior context for the external system.
String
No
"You are a helpful AI Assistant."
userMessage
User message template that defines how user input is presented to the external AI. Can include expressions.
String
Yes
-
userIdentityExpression
Expression to identify the user context for personalized responses in external system.
String
No
-
execution
Execution configuration that defines how to delegate to the external AI system. See AgentProxyExecutionDef
Object
Yes
-
agentOutcomes
List of outcome handlers that define actions to take based on proxy execution results. See OnAgentOutcomeDef
List
No
[]
loginRequired
Whether user authentication is required to interact with this proxy agent.
Boolean
No
-
groupConfig
Group configuration for multi-user or team-based proxy interactions. See GroupConfigDef
Object
No
-
Common Configuration Objects
AgentProxyExecutionDef
Agent Proxy Execution Definition. Defines how the proxy agent delegates execution to external systems, including function references and execution configurations.
functionRefCode
The function reference code for the proxy execution
String
No
definition
The execution definition for the agent proxy. See AgentProxyExecutionDefinition
Object
Yes
AgentProxyExecutionDefinition
Interface for different types of proxy execution definitions. Supports multiple execution types for connecting to external AI systems.
SimpleRestExecutionDefinition
Simple REST execution definition for connecting to external AI services via REST APIs.
type
The execution type identifier
String
Yes
url
The REST endpoint URL for the external AI service
String
Yes
method
HTTP method for the REST call
String
Yes
headers
HTTP headers to include in the request
Map<String, String>
No
queryParams
Query parameters to include in the request
Map<String, String>
No
body
Request body content
String
No
OpenApiRestExecutionDefinition
OpenAPI REST execution definition using OpenAPI schema specification for external AI services.
type
The execution type identifier
String
Yes
schema
The OpenAPI schema definition as a JSON object
JsonNode
Yes
OnAgentOutcomeDef
Agent Outcome Definition. Defines conditional actions to be performed based on the outcome of an AI agent proxy's execution. Allows for branching logic, workflow control, and custom responses based on agent results or specific conditions.
condition
Expression that must evaluate to true for this outcome to be matched
String
Yes
-
finish
Whether the agent should finish execution after this outcome action is performed
Boolean
No
true
transition
The transition definition specifying the next step in the workflow when this outcome is matched
Object
No
-
answerAfterFinish
Whether to provide an answer message after finishing this outcome action
Boolean
No
false
answerMessage
Custom message to display when this outcome is triggered and answerAfterFinish is true
String
No
-
GroupConfigDef
Group Configuration Definition. Defines the behavior of AI agent proxies when operating in group or multi-agent contexts. Controls how proxy agents interact with other agents and respond to messages in collaborative environments.
directMessageOnly
Whether the agent should only respond to messages that are directly addressed to it
Boolean
No
false
TransitionDef
Defines the flow control mechanism for moving between different states or agents in a workflow. Specifies either a target destination or workflow termination, enabling complex branching and routing logic in AI agent conversations.
end
Whether this transition marks the end of the workflow execution. When true, the workflow terminates. When false, execution continues to the target agent
Boolean
No
false
targetId
The unique identifier of the target agent or node to transition to. Must correspond to a valid agent name defined in the workflow. Ignored if 'end' is true
String
No
-
Example Configuration
Simple REST Proxy Example
{
"name": "externalLLMProxy",
"type": "aiagentproxy",
"start": false,
"systemMessage": "You are a specialized agent running on external infrastructure with enhanced capabilities.",
"userMessage": "Process this request with external AI: {{userInput}}",
"userIdentityExpression": "{{user.name}} (External Session: {{session.id}})",
"execution": {
"functionRefCode": "external-ai-service",
"definition": {
"type": "simple-rest",
"url": "https://external-ai-service.com/api/chat",
"method": "POST",
"headers": {
"Authorization": "Bearer {{config.apiKey}}",
"Content-Type": "application/json",
"User-Agent": "XBot-Proxy/1.0"
},
"queryParams": {
"model": "gpt-4o",
"stream": "false"
},
"body": "{\"messages\": [{\"role\": \"system\", \"content\": \"{{systemMessage}}\"}, {\"role\": \"user\", \"content\": \"{{userMessage}}\"}], \"max_tokens\": 1000, \"temperature\": 0.7}"
}
},
"agentOutcomes": [
{
"condition": "{{response.status}} == 'success'",
"finish": true,
"answerAfterFinish": false,
"transition": {
"targetId": "successHandler"
}
},
{
"condition": "{{response.status}} == 'error'",
"finish": true,
"answerAfterFinish": true,
"answerMessage": "External AI service encountered an error. Please try again later.",
"transition": {
"targetId": "errorHandler"
}
}
],
"groupConfig": {
"directMessageOnly": true
},
"loginRequired": true,
"transition": {
"targetId": "nextStep"
},
"answerAfterFinish": false,
"answerMessage": "External AI processing completed successfully"
}OpenAPI REST Proxy Example
{
"name": "enterpriseAIProxy",
"type": "aiagentproxy",
"start": false,
"systemMessage": "You are an enterprise AI assistant with access to company-specific knowledge and capabilities.",
"userMessage": "Enterprise query: {{userInput}}",
"userIdentityExpression": "{{user.employeeId}} - {{user.department}}",
"execution": {
"functionRefCode": "enterprise-ai-api",
"definition": {
"type": "openapi-rest",
"schema": {
"openapi": "3.0.0",
"info": {
"title": "Enterprise AI API",
"version": "1.0.0",
"description": "Enterprise AI service for internal company operations"
},
"servers": [
{
"url": "https://enterprise-ai.company.com/api/v1"
}
],
"paths": {
"/chat/completions": {
"post": {
"summary": "Create a chat completion",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"messages": {
"type": "array",
"items": {
"type": "object",
"properties": {
"role": {"type": "string"},
"content": {"type": "string"}
}
}
},
"model": {"type": "string"},
"temperature": {"type": "number"},
"max_tokens": {"type": "integer"}
}
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"choices": {
"type": "array",
"items": {
"type": "object",
"properties": {
"message": {
"type": "object",
"properties": {
"content": {"type": "string"}
}
}
}
}
}
}
}
}
}
}
}
}
}
},
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer"
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
}
},
"agentOutcomes": [
{
"condition": "{{response.choices[0].message.content}} contains 'confidential'",
"finish": false,
"transition": {
"targetId": "securityReviewAgent"
}
},
{
"condition": "{{response.usage.total_tokens}} > 500",
"finish": true,
"answerAfterFinish": true,
"answerMessage": "Response was comprehensive. Please review the detailed information provided."
}
],
"groupConfig": {
"directMessageOnly": false
},
"loginRequired": true,
"transition": {
"targetId": "followupAgent"
},
"answerAfterFinish": true,
"answerMessage": "Enterprise AI consultation completed. The response has been processed according to company policies."
}Last updated