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:

1. Reason about what tools to use
2. Execute tools with appropriate parameters
3. Observe results
4. Plan next steps

Agent Workflow

Configuration Parameters

Essential Parameters

Parameter	Description	Required	Example
llmModelId	Bedrock model identifier	Yes	anthropic.claude-haiku-4-5-20251001-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 guardrail names or parameterized guardrails (see Guardrails guide)	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)	See the Analytics guide

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-haiku-4-5-20251001-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
                }
            }
        ]
    }
}

Multiple Scoped Searches

One agent can use the same RAG backend with different retrieval scopes. Give each configuration a clear display name and description; funcName remains the real backend operation:

{
    "tools": [
        {
            "toolType": "rag",
            "name": "HR search",
            "description": "Search HR policies and benefits documents",
            "funcName": "semantic_search",
            "semanticSearchConfig": {
                "hxqlQuery": "SELECT * FROM SysContent WHERE sys_docType = 'HR'"
            }
        },
        {
            "toolType": "rag",
            "name": "Finance search",
            "description": "Search Finance policies and reports",
            "funcName": "semantic_search",
            "semanticSearchConfig": {
                "hxqlQuery": "SELECT * FROM SysContent WHERE sys_docType = 'Finance'"
            }
        }
    ]
}

No alias field is required. At runtime, the platform assigns stable internal tool names only when an agent has multiple distinct scopes for the same backend. The aliases combine the backend and snake-case configured name, such as semantic_search_hr_search and semantic_search_finance_search; a fingerprint suffix is added only if configured names normalize to the same alias. Generated names can appear in tool-call output, usage metrics, and child tool spans; each still calls semantic_search with only its own configured scope. An agent with a single semantic-search configuration continues to expose semantic_search.

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.

Content Lake Filesystem Tools

Browse and read the Content Lake document repository like a filesystem — list folders, find documents by name, read a document's extracted text, and search within one document. These complement semantic_search: use them when the agent (or the user) already knows roughly where a document lives or what it's named, rather than searching by meaning.

funcName	Description
ls	List the children (files/folders) of a folder, one level or the whole subtree
read_file	Read a document's extracted text (markdown), paged by line number
glob	Find files/folders whose name contains a substring
grep	Search for a pattern within one document's text

Like the GraphRAG tools above, these use toolType: "rag" with funcName — no semanticSearchConfig is needed since each tool takes its own explicit parameters (e.g. doc_id, pattern) rather than config-driven scoping.

{
    "name": "doc-browser",
    "displayName": "Document Browser",
    "description": "An agent that browses and reads documents by name",
    "agentType": "tool",
    "config": {
        "llmModelId": "anthropic.claude-haiku-4-5-20251001-v1:0",
        "systemPrompt": "You are a helpful assistant. Use glob to find a document by name, then read_file to read its text.",
        "tools": [
            {
                "toolType": "rag",
                "name": "find_documents",
                "description": "Find documents by name",
                "funcName": "glob"
            },
            {
                "toolType": "rag",
                "name": "read_document",
                "description": "Read a document's extracted text",
                "funcName": "read_file"
            }
        ]
    }
}

Discovery workflow

ls/glob return each document's id (Content Lake sys_id) — pass it straight into read_file or grep. read_file/grep require a Content Lake sys_id, not a Knowledge Graph hex uid (the id graph_get_node_by_uid uses).

Runtime Overrides for RAG Tools

Values set in semanticSearchConfig are defaults baked into the agent. A fixed subset of them can be overridden per invocation by passing the corresponding field at the top level of the /invoke or /invoke-stream request body — useful when the caller (not the LLM) already knows which document or filter a specific request should be scoped to. Only the fields below are supported as runtime overrides; any other semanticSearchConfig field (e.g. domainId, used by GraphRAG tools) can only be set in the agent's stored configuration.

Parameter	Type	Description
hxqlQuery	string	Overrides hxqlQuery on every rag-type tool in the agent, for this call only
hybridSearch	boolean	Overrides hybridSearch on every rag-type tool, for this call only
limit	integer	Overrides limit on every rag-type tool, for this call only
adjacentChunkRange	integer	Overrides adjacentChunkRange on every rag-type tool, for this call only
adjacentChunkMerge	boolean	Overrides adjacentChunkMerge on every rag-type tool, for this call only
rerankerTopN	integer	Overrides rerankerTopN on every rag-type tool, for this call only
enableHallucinationCheck	boolean	Overrides enableHallucinationCheck on every rag-type tool, for this call only
enableMultihopQueryRefinement	boolean	Overrides enableMultihopQueryRefinement on every rag-type tool, for this call only

Non-RAG tools (function, mcp, structured_output, task_agent, analytics) on the same agent are unaffected.

Example — scoping search to one document at invocation time:

{
    "messages": [
        { "role": "user", "content": "What does this contract say about termination?" }
    ],
    "hxqlQuery": "SELECT * FROM SysContent WHERE sys_id = '6e4a7f58-13f1-4d3f-83b9-ec86c5b7df60'"
}

This lets a caller who already knows which document to search — e.g. a document ID resolved by an upstream workflow — scope semantic search to just that document's chunks, without hardcoding the filter into the agent's configuration or relying on the LLM to construct HxQL itself.

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.

Key Constraints

• The tool must be named structured_output — the name field must be exactly "structured_output". Any other name will not be recognized.
• Only one structured_output tool is allowed per agent — configuring more than one is not supported.
• The tool is always executed — the structured_output tool is invoked for every response, regardless of whether the user's question matches the intended purpose of the agent. If a question is completely unrelated, the LLM will still attempt to populate the schema, which may produce confusing results.
• Compatible with other tools — structured_output can be configured alongside other tools (e.g., function, rag). The other tools run first to gather the information needed, and structured_output is used for the final structured response.

Configuration Examples

1. Person Information

   {
       "name": "info-extractor",
       "displayName": "Info Extractor",
       "description": "Extracts information about a person",
       "agentType": "tool",
       "config": {
           "llmModelId": "anthropic.claude-haiku-4-5-20251001-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"
   }

2. Product Information

   {
       "name": "product-info-extractor",
       "displayName": "Product Info Extractor",
       "description": "Extracts information about a product",
       "agentType": "tool",
       "config": {
           "llmModelId": "anthropic.claude-haiku-4-5-20251001-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"]
                   }
               }
           ]
       }
   }

3. Event Detail with nested schemas

   {
       "name": "event-detailer",
       "displayName": "Event Detailer",
       "description": "Extracts information about an event",
       "agentType": "tool",
       "config": {
           "llmModelId": "anthropic.claude-haiku-4-5-20251001-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"]
                   }
               }
           ]
       }
   }

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:

1. 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, etc.
               }
           }
       ],
       "role": "user"
   }

2. 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, etc.
               }
           }
       ],
       "role": "user"
   }

3. 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, etc.
               }
           }
       ],
       "role": "user"
   }

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

Best Practices for Images

• Specify mediaType: Always include the correct mediaType (e.g., image/jpeg, image/png) in the source object. This is essential for proper processing.
• Supported Formats: Common formats such as JPG and PNG are supported. The mediaType you declare is trusted as-is; the service validates the source structure (base64 encoding, URL, or S3-path format) but does not inspect the image bytes to confirm they match the declared mediaType, so make sure the data and mediaType are consistent.
• 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:

1. 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"
   }

2. 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.

3. 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

1. System Prompts

   • Be specific about the agent's role
   • Define clear boundaries
   • Include error handling instructions

2. Tool Selection

   • Choose tools that complement each other
   • Provide clear tool descriptions
   • Limit tools to necessary ones only

3. Error Handling

   • Include retry logic
   • Provide fallback options
   • Handle tool failures gracefully

4. Guardrails

   • For comprehensive information on discovering, configuring, and merging guardrails, see the Guardrails guide.

Best Practices for Structured Output

1. Schema Design

   • Keep schemas focused and specific
   • Use clear property names
   • Include descriptions for complex fields
   • Mark required fields appropriately

2. Data Validation

   • Use appropriate data types
   • Include format specifications when needed
   • Consider adding enum values for restricted choices

3. 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-haiku-4-5-20251001-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."
        }
    ]
}

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.

Exception: if the agent is configured with a structured_output tool, the concatenated text response is itself a single valid JSON object matching the configured outputSchema — same as the non-streaming /invoke response.

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. Known failure modes (guardrail blocks, max_tokens truncation, rate limiting, context-window overflow) always terminate the stream with an explicit IncompleteChunk — see Processing Streamed Data. For anything else, check the logs.

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.
502	Bad Gateway	The model's response was cut off because it reached the configured inferenceConfig.maxTokens limit. Increase maxTokens and retry. Only returned by /invoke; the streaming endpoint instead terminates with an IncompleteChunk where incompleteDetails.reason is "error" (see Processing Streamed Data).

Future Enhancements

• Additional tool types planned
• Enhanced memory capabilities
• Dynamic tool loading