tools-setup

Adding Tools to an AI Agent

What are tools?

Tools give an AI Agent capabilities beyond conversation — calling APIs, executing code, or searching knowledge bases. Without tools, an agent can only chat.

Steps

1. Create the agent first: create_ai_agent { projectId, name, description } (create_tool requires an agent with an auto-provisioned flow)
2. create_tool { aiAgentId, toolType, name, config }
3. The tool is automatically wired into the agent's flow
4. Test with talk_to_agent

Rule of thumb: each tool in an agent flow should have a unique toolId. If you need more logic, parameters, validation, or HTTP calls for that tool, add them inside the same tool branch instead of creating another tool with the same toolId.

Parameter schema rules (config.parameters)

parameters is a JSON Schema string that Cognigy passes VERBATIM to the LLM provider. create_tool / update_tool validate it and reject violations, because a broken schema either fails every conversation turn with a provider 400 (strict models) or is silently dropped (the tool is called with no arguments). The contract:

• Top level: {"type":"object","properties":{...},"required":[...]} — required is mandatory (use [] if nothing is required).
• EVERY property needs "type" AND "description". Allowed types: string, number, integer, boolean, object, array, null.
• array properties need "items". Nested objects with "properties" also need their own "required".
• "additionalProperties": false is injected automatically at every object level.
• Strict-mode models (OpenAI Responses API, e.g. gpt-5.x, where strict is forced on): list EVERY property key in required; make a parameter optional with a nullable type — {"type":["string","null"],"description":"..."}. Non-strict providers ignore this, so it is the safe default.
• Nested object properties and integer are valid at runtime but not renderable by the Cognigy UI's graphical parameter builder — the node's Parameters section then shows the raw JSON editor. That is cosmetic; prefer flat schemas when you don't need nesting.