Tool Agent

What is an Agent?

An agent is an AI system that can perceive its environment, make decisions, and take actions to achieve specific goals. In our context, agents are specialized LLM-powered systems that can:

Understand natural language inputs
Plan sequences of actions
Use tools to accomplish tasks
Maintain context through conversations
Generate coherent responses

Tool Agent Architecture

Tool Agents use a ReAct (Reasoning + Acting) pattern combined with function calling capabilities from LLM providers. This enables them to:

Reason about what tools to use
Execute tools with appropriate parameters
Observe results
Plan next steps

Agent Workflow

Configuration Parameters

Essential Parameters

Parameter	Description	Required	Example
`llmModelId`	Bedrock model identifier	Yes	`anthropic.claude-3-haiku-20240307-v1:0`
`systemPrompt`	Instructions for the agent	Yes	"You are a helpful assistant..."
`tools`	Array of available tools	Yes	See tools configuration
`inferenceConfig`	LLM parameters	No	See Inference Config below
`guardrails`	List of guardrails names	No	`["HAIP-Profanity", "HAIP-Insults-High"]`

Inference Config

Parameter	Description	Default
`maxTokens`	Maximum number of tokens to generate	`4000`
`temperature`	Temperature for inference (0.0 to 1.0)	`0.0`
`maxRetries`	Maximum number of retries on failure	`10`
`timeout`	Timeout for inference in seconds	`3600`

Tool Configuration

Each tool requires toolType and varies by type:

Tool Type	Description	Additional Fields
`function`	Call a predefined function	`funcName` (required)
`rag`	Search and retrieve from Content Lake or Knowledge Graph	`funcName` (required), `semanticSearchConfig` (optional)
`structured_output`	Force JSON output matching a schema	`outputSchema` (required), `modelId` (optional — model for LLM-assisted schema parsing)
`task_agent`	Invoke a Task Agent as a tool	`agentId` (required), `agentVersion` (optional, default `"latest"`)
`mcp`	Connect to an MCP server for external tools	`mcpServerReferences` (required)
`analytics`	Execute Python code in a secure sandbox (experimental)	—

All tool types except analytics and task_agent require name and description fields. For task_agent, these are automatically populated from the referenced agent.

Max Retries

When invoking agents that error for any reason (E.g., input is too large, network issue, etc.), the client you're using to make the request could time out. To help with this, you could set maxRetries in the inferenceConfig to a low number (E.g., 2).

Example Configurations

Basic Example

{
    "name": "multiplier",
    "displayName": "Multiplier",
    "description": "An agent that multiplies two numbers",
    "agentType": "tool",
    "config": {
        "llmModelId": "anthropic.claude-3-haiku-20240307-v1:0",
        "systemPrompt": "You are a helpful assistant that uses available tools to answer questions.",
        "tools": [
            {
                "toolType": "function",
                "name": "multiply",
                "description": "Multiplies two numbers",
                "funcName": "multiply"
            }
        ],
        "inferenceConfig": {
            "maxTokens": 4000,
            "temperature": 0.7
        },
        "guardrails": ["HAIP-Insults-Low"]
    }
}

Example Usage

This basic configuration enables the agent to perform multiplication operations. More complex configurations can be created by adding additional tools and customizing parameters.

RAG Tools

RAG (Retrieval-Augmented Generation) tools let your agent search and retrieve information from Content Lake and the Knowledge Graph. There are two categories:

Semantic Search (semantic_search) — vector/hybrid search over Content Lake document chunks
GraphRAG (graph_*) — structured search, navigation, and exploration of the Knowledge Graph

RAG tools use toolType: "rag" and accept an optional semanticSearchConfig object for configuration. Values in semanticSearchConfig are hidden from the LLM and automatically injected into every tool call.

Semantic Search Config

Parameter	Description	Required
`domainId`	Knowledge Graph domain ID. Required for all `graph_*` tools.	For GraphRAG
`hxqlQuery`	HXQL query for Content Lake filtering (e.g., scope to specific documents)	No
`hybridSearch`	Enable combined vector + full-text search	No
`limit`	Maximum chunks to retrieve	No
`rerankerTopN`	Results to keep after neural reranking	No
`enableHallucinationCheck`	Enable hallucination detection	No
`enableMultihopQueryRefinement`	Enable multi-hop query refinement	No

Semantic Search Example

A single tool that searches Content Lake using hybrid vector + keyword search:

{
    "name": "doc-search-agent",
    "displayName": "Document Search Agent",
    "description": "An agent that searches documents using semantic search",
    "agentType": "tool",
    "config": {
        "llmModelId": "anthropic.claude-haiku-4-5-20251001-v1:0",
        "systemPrompt": "You are a helpful assistant. Use the semantic search tool to find relevant information before answering questions.",
        "tools": [
            {
                "toolType": "rag",
                "name": "semantic_search",
                "description": "Search documents using semantic search",
                "funcName": "semantic_search",
                "semanticSearchConfig": {
                    "hxqlQuery": "SELECT * FROM SysContent WHERE documentType = 'Policy'",
                    "hybridSearch": true
                }
            }
        ]
    }
}

GraphRAG Tools

GraphRAG tools provide structured access to the Knowledge Graph. All GraphRAG tools require domainId in semanticSearchConfig.

Available GraphRAG Tools

`funcName`	Description
`graph_search_business_objects`	Search for BusinessObjects (vendors, contracts, projects) by name or type
`graph_search_global_entities`	Search for entities (people, organizations, locations) by name, type, or role
`graph_search_documents`	Search documents by keywords, doc_type, or date range
`graph_search_vector_db`	Hybrid vector search over document chunks with KG resolution
`graph_search_local_entity`	Search for entity mentions at the chunk level
`graph_search_metadata_kv`	Search structured metadata key-value pairs
`graph_explore_connections`	Explore connections from a node (360-degree view)
`graph_get_node_by_uid`	Get full details of a single node by UID
`graph_execute_dql`	Execute a raw DQL query (escape hatch for complex operations)
`graph_find_related_entities`	Find entities that co-occur in documents with a given entity
`graph_rank_entities`	Rank entities of a type by document frequency

GraphRAG Example

An agent configured with multiple GraphRAG tools for knowledge graph exploration:

{
    "name": "kg-explorer",
    "displayName": "Knowledge Graph Explorer",
    "description": "An agent that explores and retrieves information from the Knowledge Graph",
    "agentType": "tool",
    "config": {
        "llmModelId": "anthropic.claude-sonnet-4-6-20250514-v1:0",
        "systemPrompt": "You are a knowledge graph assistant. Use the graph tools to search for entities, documents, and relationships to answer user questions. Start with broad searches, then drill into specific nodes.",
        "tools": [
            {
                "toolType": "rag",
                "funcName": "graph_search_global_entities",
                "name": "Search Entities",
                "description": "Search for people, organizations, and locations in the knowledge graph",
                "semanticSearchConfig": { "domainId": "<your-domain-id>" }
            },
            {
                "toolType": "rag",
                "funcName": "graph_search_documents",
                "name": "Search Documents",
                "description": "Search documents by keywords, type, or date range",
                "semanticSearchConfig": { "domainId": "<your-domain-id>" }
            },
            {
                "toolType": "rag",
                "funcName": "graph_search_vector_db",
                "name": "Semantic Chunk Search",
                "description": "Hybrid vector search over document chunks with KG resolution",
                "semanticSearchConfig": {
                    "domainId": "<your-domain-id>",
                    "hxqlQuery": "SELECT * FROM SysContent"
                }
            },
            {
                "toolType": "rag",
                "funcName": "graph_explore_connections",
                "name": "Explore Connections",
                "description": "Explore all connections from a node in the knowledge graph",
                "semanticSearchConfig": { "domainId": "<your-domain-id>" }
            },
            {
                "toolType": "rag",
                "funcName": "graph_get_node_by_uid",
                "name": "Get Node Details",
                "description": "Get full details of a specific node by its UID",
                "semanticSearchConfig": { "domainId": "<your-domain-id>" }
            }
        ],
        "inferenceConfig": {
            "maxTokens": 8000
        }
    }
}

Choosing Tools

You don't need to include all 11 GraphRAG tools. Pick the ones relevant to your use case. For most scenarios, graph_search_global_entities, graph_search_documents, graph_search_vector_db, and graph_explore_connections provide a good starting set.

Structured Output Tools

Tool Agents can be configured to output structured data in JSON format using the structured_output tool type. This is useful when you need to extract specific information in a consistent format or transform unstructured text into structured data.

Configuration Examples

Person Information

{
    "name": "info-extractor",
    "displayName": "Info Extractor",
    "description": "Extracts information about a person",
    "agentType": "tool",
    "config": {
        "llmModelId": "anthropic.claude-3-haiku-20240307-v1:0",
        "systemPrompt": "You are a helpful assistant that extracts structured information.",
        "tools": [
            {
                "toolType": "structured_output",
                "name": "structured_output",
                "description": "Extracts structured information about a person from text",
                "outputSchema": {
                    "type": "object",
                    "properties": {
                        "name": {
                            "type": "string",
                            "description": "Full name of the person"
                        },
                        "age": {
                            "type": "integer",
                            "description": "Age of the person"
                        },
                        "occupation": {
                            "type": "string",
                            "description": "Person's job or profession"
                        }
                    },
                    "required": ["name"]
                }
            }
        ]
    }
}

Sample Output

Input: "John Doe is a 35-year-old software engineer"

{
    "name": "John Doe",
    "age": 35,
    "occupation": "software engineer"
}

Product Information

{
    "name": "product-info-extractor",
    "displayName": "Product Info Extractor",
    "description": "Extracts information about a product",
    "agentType": "tool",
    "config": {
        "llmModelId": "anthropic.claude-3-haiku-20240307-v1:0",
        "systemPrompt": "You are a helpful assistant that extracts product information.",
        "tools": [
            {
                "toolType": "structured_output",
                "name": "structured_output",
                "description": "Extracts product information from text",
                "outputSchema": {
                    "type": "object",
                    "properties": {
                        "productName": { "type": "string" },
                        "price": { "type": "number" },
                        "currency": { "type": "string" },
                        "inStock": { "type": "boolean" }
                    },
                    "required": ["productName", "price"]
                }
            }
        ]
    }
}

Event Detail with nested schemas

{
    "name": "event-detailer",
    "displayName": "Event Detailer",
    "description": "Extracts information about an event",
    "agentType": "tool",
    "config": {
        "llmModelId": "anthropic.claude-3-haiku-20240307-v1:0",
        "systemPrompt": "You are a helpful assistant that extracts event information.",
        "tools": [
            {
                "toolType": "structured_output",
                "name": "structured_output",
                "description": "Extracts event information from text",
                "outputSchema": {
                    "type": "object",
                    "properties": {
                        "eventName": { "type": "string" },
                        "date": { "type": "string", "format": "date" },
                        "location": { "type": "string" },
                        "attendees": {
                            "type": "array",
                            "items": { "type": "string" }
                        }
                    },
                    "required": ["eventName", "date"]
                }
            }
        ]
    }
}

Analytics Tool

Experimental Feature

The Analytics tool is currently experimental. Functionality, endpoints, and behavior may change in future releases.

Tool Agents can be configured to execute code in a secure sandbox environment using the Analytics tool. This enables advanced data analysis, visualization generation, and programmatic processing of uploaded files. The agent writes and runs Python code on your behalf, returning text results and optionally generating downloadable artifacts (e.g., charts, transformed datasets).

Agent Configuration

The agent must be configured with the analytics tool. No additional tool configuration (parameters, schemas, etc.) is required:

{
    "name": "data-analyst",
    "displayName": "Data Analyst",
    "description": "An agent that analyzes data and generates visualizations",
    "agentType": "tool",
    "config": {
        "llmModelId": "anthropic.claude-haiku-4-5-20251001-v1:0",
        "systemPrompt": "You are a data analysis assistant. Use the code execution tool to analyze uploaded files, generate visualizations, and provide statistical insights.",
        "tools": [
            {
                "toolType": "analytics"
            }
        ]
    }
}

Workflow

The workflow follows three steps:

Upload your data file — Request a presigned URL and upload your file to S3
Invoke the agent — Send a message referencing the uploaded file by its ID
Download results — Retrieve any generated artifacts via the URLs in the response

Step 1: Upload Your Data File

First, request a presigned upload URL via the /v1/files endpoint:

Endpoint: POST /v1/files

curl -X POST "/v1/files" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "fileName": "sales_data.csv",
    "mediaType": "text/csv",
    "sizeBytes": 1024,
    "accessScope": { "type": "user" }
  }'

Parameters:

Parameter	Description	Required
`fileName`	Name of the file (e.g., `sales_data.csv`)	Yes
`mediaType`	MIME type — must be a supported type (e.g., `text/csv`, `application/pdf`)	Yes
`sizeBytes`	Size of the file in bytes (max 100 MB)	Yes
`accessScope`	Access scope object with a `type` field: `"user"` for private files (default) or `"tenant"` for organization-wide sharing	No

Response:

{
  "fileId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "fileName": "sales_data.csv",
  "sizeBytes": 1024,
  "createdAt": "2026-03-09T12:00:00Z",
  "uploadUrl": "https://code-interpreter-bucket.s3.amazonaws.com/...",
  "uploadExpiresAt": "2026-03-09T13:00:00Z"
}

Save the fileId (you will reference it when invoking the agent) and the uploadUrl (used to upload the file).

Next, upload your file to the presigned URL using a PUT request. Both Content-Type and Content-Length headers are signed into the URL, so they must match the values declared when the upload session was created. Most HTTP clients set Content-Length automatically.

curl -X PUT "https://code-interpreter-bucket.s3.amazonaws.com/..." \
  -H "Content-Type: text/csv" \
  -H "Content-Length: <sizeBytes>" \
  --data-binary @sales_data.csv

A successful upload returns HTTP 200 with no body.

warning

Presigned upload URLs expire after 1 hour. If the URL expires, request a new one via POST /v1/files.

warning

All uploaded files are automatically deleted after 24 hours in accordance with the S3 bucket's 1-day lifecycle policy. If you need to re-analyze a file after that period, you must upload it again.

Step 2: Invoke the Agent

Send your analysis request to the agent, referencing the uploaded file by its fileId:

curl -X POST "/v1/agents/{agent_id}/versions/{version_id}/invoke" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "Analyze the sales data and create a bar chart showing total sales by category. Include summary statistics."
          },
          {
            "type": "file_analysis",
            "fileId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "fileName": "sales_data.csv",
            "mediaType": "text/csv"
          }
        ]
      }
    ]
  }'

The message content array contains two parts:

Field	Description
`type: "text"`	Your natural language analysis request
`type: "file_analysis"`	Reference to the uploaded file — requires `fileId`, `fileName`, and `mediaType`

The backend downloads the file internally using the fileId; you do not need to provide a download URL.

Depending on your prompt, the agent may:

Generate artifacts (charts, transformed files) — returned as downloadable URLs in the response
Return text-only results — e.g., answering a question about the data, providing summary statistics, or describing patterns without generating a file

Step 3: Download Results

When the agent generates artifacts (visualizations, processed files, etc.), the response includes download URLs:

{
  "output": [
    {
      "type": "text",
      "text": "Here is the analysis:\n\nStatistical Summary:\n- Total Sales: $1,000.00\n- Average: $200.00\n- Max: $300.00\n- Min: $100.00\n\n[Sales by Category](https://artifacts.agents.ai.app.hyland.com/account/env/chart-uuid-filename.png)"
    }
  ]
}

Download the artifact using the URL from the response:

curl "https://artifacts.agents.ai.app.hyland.com/account/env/chart-uuid-filename.png" -o sales_chart.png

warning

Generated artifacts are stored in S3 with a 1-day lifecycle policy. Files are automatically deleted after 24 hours, after which the CloudFront URLs will no longer work. Download any artifacts you need to keep within 24 hours of receiving the response, or re-execute the analysis to generate new ones.

Supported Data Formats

The following file types can be uploaded via the /v1/files endpoint:

Format	MIME Type
Plain Text	`text/plain`
CSV	`text/csv`
TSV	`text/tab-separated-values`
HTML	`text/html`
Markdown	`text/markdown`
XML	`text/xml`, `application/xml`
JSON	`application/json`
Excel	`application/vnd.ms-excel`, `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`

caution

This feature is experimental. The list of supported MIME types may change as the functionality is finalized.

Example Prompts

Goal	Example Prompt
Summary statistics	"Provide summary statistics including mean, median, and standard deviation for all numeric columns."
Visualization	"Create a bar chart showing sales by category and include percentage labels."
Data quality	"Generate a data quality report: missing values, duplicates, and outlier detection."
Question answering	"How many unique customers are in this dataset?"
Time series	"Plot a line chart of monthly revenue with a 3-month moving average."

Best Practices for Code Execution

Be specific in your analysis requests — clearly describe the desired output (chart type, columns, metrics).
Use descriptive filenames (e.g., sales_q1_2026.csv instead of data.csv) to help the agent understand context.
Download artifacts promptly — generated files in S3 have a TTL and will expire.
Break complex analyses into steps — for large or multi-part analyses, consider sending separate requests.
Verify file format — ensure the mediaType matches the actual file format.

Working with Images

Tool Agents support processing images alongside text inputs. Images are provided within the content array. Each image is represented by an item with type: "image", containing a source object that specifies the origin (URL, S3 path, or base64), mediaType, and the actual image data or reference.

Images can be provided in three primary ways:

URL-based images: Provide a direct HTTPS URL to the image. The mediaType field indicates the image format.

{
    "content": [
        {
            "type": "text",
            "text": "What's in this image?"
        },
        {
            "type": "image",
            "source": {
                "type": "url",
                "url": "https://example.com/image.jpg",
                "mediaType": "image/jpeg" // Supported: image/jpeg, image/png, image/tiff, etc.
            }
        }
    ],
    "role": "user"
}

Note: For TIFF images (mediaType: "image/tiff"), the URL must end with a .tiff or .tif extension.

S3 path images: Reference an image stored in an S3 bucket. Specify the S3 path and the mediaType.

{
    "content": [
        {
            "type": "text",
            "text": "Analyze this image from S3"
        },
        {
            "type": "image",
            "source": {
                "type": "s3_path",
                "path": "s3://bucket-name/path/to/image.png",
                "mediaType": "image/png" // Supported: image/jpeg, image/png, image/tiff, etc.
            }
        }
    ],
    "role": "user"
}

Note: For TIFF images (mediaType: "image/tiff"), the S3 path must point to a file with a .tiff or .tif extension.

Base64-encoded images: Embed the image data directly as a base64 encoded string. The mediaType is crucial here.

{
    "content": [
        {
            "type": "text",
            "text": "Describe this embedded image"
        },
        {
            "type": "image",
            "source": {
                "type": "base64",
                "data": "<base64-encoded-image-data>",
                "mediaType": "image/png" // Supported: image/jpeg, image/png, image/tiff, etc.
            }
        }
    ],
    "role": "user"
}

Note: The mediaType field is mandatory and crucial for correctly interpreting the base64 data. For image/tiff, the image data itself is validated (e.g., for correct TIFF format based on its magic number).

Best Practices for Images

Specify mediaType: Always include the correct mediaType (e.g., image/jpeg, image/png, image/tiff) in the source object. This is essential for proper processing.
Supported Formats: While many standard image formats can be indicated via mediaType, ensure your specific use case is tested. JPG, PNG, and TIFF are explicitly supported and validated.
TIFF Specifics:
- For URL or S3 sources of TIFF images, ensure the file path ends with .tiff or .tif.
- For base64 encoded TIFF images, the data integrity (magic number) is checked.
Image Source: Clearly define the image source with its type (url, s3_path, base64) and the corresponding data field (url, path, data).
Size and Prompts: Keep image sizes reasonable (refer to any documented limits) to avoid timeouts and include clear text prompts to guide the agent's analysis.
Costs: Be mindful of potential costs and rate limits when processing multiple or large images.

Working with Documents

Tool Agents can process various types of documents as part of their input. This allows you to provide rich context to the agent for tasks like summarization, question answering based on specific texts, or data extraction. Documents are included in the content array of a message, similar to images. Each document is represented by an item with type: "document", containing a source object that specifies the origin (URL, S3 path, or base64), mediaType, and the actual document data or reference. The name field is required (1-200 chars) and helps the agent identify specific documents.

Supported File Types: PDF, CSV, XLS, XLSX, HTML, TXT, MD. The mediaType field in the source object should correspond to the actual format of the document (e.g., application/pdf for PDF, text/csv for CSV). Maximum File Size: 4.5 MB Document Limit: Up to 5 documents can be included per message.

Documents can be provided in three primary ways:

URL-based documents: Provide a direct HTTPS URL to the document. The mediaType field indicates the document format.

{
    "content": [
        {
            "type": "text",
            "text": "Summarize the attached report."
        },
        {
            "type": "document",
            "source": {
                "type": "url",
                "url": "https://example.com/annual_report.pdf",
                "mediaType": "application/pdf"
            },
            "name": "Annual Report 2023"
        }
    ],
    "role": "user"
}

Base64-encoded documents: Embed the document data directly as a base64 encoded string. The mediaType is crucial here.

{
    "content": [
        {
            "type": "text",
            "text": "What are the main points in this text file?"
        },
        {
            "type": "document",
            "source": {
                "type": "base64",
                "data": "<base64-encoded-document-content>",
                "mediaType": "application/pdf"
            },
            "name": "Meeting Notes"
        }
    ],
    "role": "user"
}

Note: The mediaType field is mandatory and crucial for correctly interpreting the base64 data.

S3 path documents: Reference a document stored in an S3 bucket. Specify the S3 path and the mediaType.

{
    "content": [
        {
            "type": "text",
            "text": "Analyze this document from S3"
        },
        {
            "type": "document",
            "source": {
                "type": "s3_path",
                "path": "s3://bucket-name/path/to/document.xlsx",
                "mediaType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
            },
            "name": "Sales Data Q1"
        }
    ],
    "role": "user"
}

Note: The mediaType field is mandatory and crucial for correctly interpreting the document.

The name field is required and helps the agent identify and refer to specific documents, especially when multiple documents are provided. Allowed characters: alphanumeric, single spaces, hyphens, parentheses, and square brackets.

Best Practices for Documents

Use name: Provide a descriptive name for each document (required, 1-200 chars). Use a neutral name to avoid prompt injection risks.
Specify mediaType: Always include the correct mediaType (e.g., application/pdf, text/csv, application/msword) in the source object. This is essential for proper processing and should correspond to one of the Supported File Types.
Respect Limits: Do not exceed the 5-document limit per message or the 4.5 MB file size limit.
Choose the Right Source Type:
- Use source.type: "url" with source.url for publicly accessible documents.
- Use source.type: "s3_path" with source.path for documents in S3 (once feature is available).
- Use source.type: "base64" with source.data for smaller files or when direct content embedding is necessary. Ensure proper base64 encoding.
Clear Prompts: Accompany documents with clear text prompts instructing the agent on what to do with them.
Supported Formats: Ensure your documents are in one of the supported file formats and the mediaType accurately reflects this.

Best Practices

System Prompts
- Be specific about the agent's role
- Define clear boundaries
- Include error handling instructions
Tool Selection
- Choose tools that complement each other
- Provide clear tool descriptions
- Limit tools to necessary ones only
Error Handling
- Include retry logic
- Provide fallback options
- Handle tool failures gracefully

Best Practices for Structured Output

Schema Design
- Keep schemas focused and specific
- Use clear property names
- Include descriptions for complex fields
- Mark required fields appropriately
Data Validation
- Use appropriate data types
- Include format specifications when needed
- Consider adding enum values for restricted choices
Error Handling
- Provide fallback values for optional fields
- Handle missing or invalid data gracefully
- Include validation messages in the schema

Invoking a Tool Agent

Standard Invocation

POST /v1/agents/{agent_id}/versions/{version_id}/invoke

Example Request:

{
    "messages": [
        {
            "role": "user",
            "content": "What is 5 times 20?"
        }
    ]
}

Example Response:

{
    "object": "response",
    "createdAt": 1741705500,
    "model": "anthropic.claude-3-haiku-20240307-v1:0",
    "output": [
        {
            "type": "message",
            "status": "completed",
            "role": "assistant",
            "content": [
                {
                    "type": "output_text",
                    "text": "The result of 5 times 20 is 100."
                }
            ]
        }
    ]
}

tip

Use latest as the version_id to invoke the most recent version of the agent.

Multi-Turn Conversation

Tool Agents support multi-turn conversations by passing previous messages in the messages array. The last message must always have role: "user".

Session-Based Memory

Tool agents support optional session-based short-term memory. Add an X-Session-ID header with a consistent UUID to maintain conversation context across multiple invocations. The platform does not auto-generate session IDs — you must generate and manage them yourself (any valid UUID).

{
    "messages": [
        {
            "role": "user",
            "content": "What is 5 times 20?"
        },
        {
            "role": "assistant",
            "content": "The result of 5 times 20 is 100."
        },
        {
            "role": "user",
            "content": "Now divide that by 4."
        }
    ]
}

Invocation with Guardrails

Additional guardrails can be passed at invocation time to apply to that specific request only:

{
    "messages": [
        {
            "role": "user",
            "content": "What is 5 times 20?"
        }
    ],
    "guardrails": ["HAIP-Hate-High", "HAIP-Insults-Low"]
}

Limitations

inferenceConfig.timeout controls the per-request LLM inference timeout (default 3600s); it is not a tool-execution timeout. MCP tool execution has its own configuration.timeoutSeconds (1–300s) set on the registered MCP server.

Streaming Support

Tool agents support streaming responses through the unified /v1/agents/{agent_id}/versions/{version_id-or-latest}/invoke-stream endpoint:

Example Request:

{
    "messages": [
        {
            "role": "user",
            "content": "Explain how multiplication works."
        }
    ]
}

tip

When using streaming, responses come in chunks. Each chunk is a valid JSON object containing a portion of the complete response. The concatenation of all chunks forms the complete text response, which is not in JSON format.

tip

Due to the nature of streaming, returning data chunk by chunk, failures that occur during runtime are difficult to return to the client. Therefore, the returned status code might be a 200, but we do our best to return the error in the response. However, it's also difficult doing that, as silent failures could occur. Please check the logs for errors that occur.

Error Responses

When a request fails, the API returns a JSON error response in the following format:

{
    "status": 400,
    "error": "HTTPException",
    "message": "Description of what went wrong"
}

Common Errors

Status	Error	Description
`400`	Bad Request	Invalid agent configuration (e.g., missing `tools`, invalid `toolType`, malformed `outputSchema`), missing required fields, or invalid invocation parameters.
`401`	Unauthorized	Missing or expired access token. Re-authenticate to obtain a new token.
`403`	Forbidden	Insufficient permissions for the requested operation. Verify your IAM user group permissions.
`404`	Not Found	Agent ID or version does not exist. Use `GET /v1/agents` to verify available agents.

Future Enhancements

Additional tool types planned
Enhanced memory capabilities
Dynamic tool loading

What is an Agent?​

Tool Agent Architecture​

Agent Workflow​

Configuration Parameters​

Essential Parameters​

Inference Config​

Tool Configuration​

Max Retries​

Example Configurations​

Basic Example​

RAG Tools​

Semantic Search Config​

Semantic Search Example​

GraphRAG Tools​

Available GraphRAG Tools​

GraphRAG Example​

Structured Output Tools​

Configuration Examples​

Analytics Tool​

Agent Configuration​

Workflow​

Step 1: Upload Your Data File​

Step 2: Invoke the Agent​

Step 3: Download Results​

Supported Data Formats​

Example Prompts​

Working with Images​

Working with Documents​

Best Practices​

Best Practices for Structured Output​

Invoking a Tool Agent​

Standard Invocation​

Multi-Turn Conversation​

Invocation with Guardrails​

Limitations​

Streaming Support​

Error Responses​

Common Errors​

Future Enhancements​

What is an Agent?

Tool Agent Architecture

Agent Workflow

Configuration Parameters

Essential Parameters

Inference Config

Tool Configuration

Max Retries

Example Configurations

Basic Example

RAG Tools

Semantic Search Config

Semantic Search Example

GraphRAG Tools

Available GraphRAG Tools

GraphRAG Example

Structured Output Tools

Configuration Examples

Analytics Tool

Agent Configuration

Workflow

Step 1: Upload Your Data File

Step 2: Invoke the Agent

Step 3: Download Results

Supported Data Formats

Example Prompts

Working with Images

Working with Documents

Best Practices

Best Practices for Structured Output

Invoking a Tool Agent

Standard Invocation

Multi-Turn Conversation

Invocation with Guardrails

Limitations

Streaming Support

Error Responses

Common Errors

Future Enhancements