Agent Creation

Building a Cognigy AI Agent

Prerequisites

• A project (use list_resources { resourceType: "project" } to find one, or let create_ai_agent create one)
• A working LLM resource in the target project before testing the agent

Steps

1. list_resources { resourceType: "project" } — inspect all projects
2. Choose the target project
   • If it already exists: use its projectId
   • If the user wants a new project: call create_ai_agent without projectId, keep the returned projectId, and if llmStatus is "unknown" continue with the LLM reuse steps below before testing the agent
3. Run list_resources { resourceType: "llm_model", projectId } — check whether the target project already has a reusable LLM with a non-empty connectionId
4. If the target project has no reusable LLM, check the other projects for reusable LLMs
   • Run list_resources { resourceType: "llm_model", projectId } for each other project
   • Choose only candidates whose llm_model has a non-empty connectionId
   • Do not treat an LLM without connectionId as a valid reuse candidate
5. If another project already has a reusable LLM, transfer the required model set together with its connection resource(s):
   • manage_packages { operation: "list_exportable", projectId: "" }
   • If this workflow will use knowledge, identify the source project's exact Knowledge Search model and embedding model before exporting anything
   • manage_packages { operation: "export", projectId: "", resourceIds: ["", "", ""], name: "llm-transfer" }
   • manage_packages { operation: "upload_and_inspect", projectId: "", filePath: "" }
   • manage_packages { operation: "import", projectId: "", packageId: "" }
   • list_resources { resourceType: "llm_model", projectId: "" } — verify the required models are present before testing or continuing setup
6. Only if no reusable LLM with connectionId exists, or the package transfer failed: setup_llm { projectId, provider: "openAI", modelType: "gpt-4o", apiKey }
   • With isDefault: true (the default), agents auto-use this LLM — no extra step needed.
   • Save the referenceId from the response if you need to assign it explicitly later. (See the llm-providers skill for valid provider/modelType values)
7. create_ai_agent { projectId, name, description } — Returns: agent, flow, endpoint, endpointUrl — The default LLM is automatically assigned to the agent's job node. If llmStatus is "configured", no extra step is needed.
8. (Only if llmStatus is "unknown" after create) Do not test yet. First repeat steps 4-6 for the returned projectId, then assign LLM to agent if needed: update_ai_agent { aiAgentId, jobConfig: { llmProviderReferenceId: "<referenceId from step 4 or 5>" } }
9. Only after the project has a confirmed working LLM: talk_to_agent { endpointUrl, message }
10. Refine the agent using update_ai_agent — see "All configuration fields" below
11. Repeat 9-10 until satisfied

Adding tools (optional)

11. create_tool { aiAgentId, toolType, name, config } (See the tools-setup skill for tool types and config)
12. talk_to_agent — test with tool-triggering messages
13. Repeat 8-12 until satisfied

Important: before creating a new tool, inspect the existing agent flow/tools first and make sure you are not reusing an existing toolId. Tool IDs must be unique within an agent flow.

All configuration fields (update_ai_agent)

update_ai_agent updates two layers: the AI Agent resource and the AI Agent Job Node.

Agent-level fields (the agent's identity)

Job-level fields (jobConfig — how the agent performs its job)

Example: fully configured agent

update_ai_agent {
  aiAgentId: "...",
  name: "Acme Support Bot",
  description: "You are a friendly and professional customer support agent for Acme Corp. You help customers with orders, returns, and product questions. You maintain a warm but efficient tone.",
  instructions: "Never share internal pricing or competitor comparisons. Always verify identity before account changes.",
  jobConfig: {
    jobName: "Customer Support Specialist",
    jobDescription: "Handle customer inquiries about orders, returns, shipping, and product information. You have access to the order database and knowledge base.",
    jobInstructions: "1. Greet the customer warmly. 2. Identify their issue. 3. Use the search tool to look up relevant information. 4. Provide a clear answer. 5. Ask if there is anything else you can help with.",
    temperature: 0.3,
    maxTokens: 2000
  }
}

How the fields work together

• description (persona): "Who am I?" — The agent's identity, personality, and tone
• instructions (guardrails): "What must I always/never do?" — Global constraints and policies
• jobName: "What is my role?" — The job title
• jobDescription: "What is my scope?" — What the job covers, what tools are available, what to escalate
• jobInstructions: "How do I do my job?" — Step-by-step procedures, output formats, decision trees
• temperature/maxTokens: "How do I think?" — LLM generation parameters

Always use ALL relevant fields when configuring an agent. Do not put everything in description alone — distribute the configuration across the appropriate fields for best results.

LLM Prompt node — explicit request ONLY

Use the LLM Prompt node only when the user asks for it by name, e.g. "create an agent using an LLM Prompt node." Otherwise, build agents with the AI Agent node.

When (and only when) the user explicitly asked for it:

• New agent: create_ai_agent { name, agentNodeType: "llmPrompt", systemPrompt: "..." } — provisions project + flow + LLM Prompt node + REST endpoint. There is NO agent resource in this mode.
• systemPrompt is the full persona, job, and guardrail definition.
• Iterate with manage_flow_nodes { operation: "update", flowId, nodeId, config: { prompt } } — NOT update_ai_agent (there is no agent to update).
• Tools: create_tool { flowId, ... } (only tool/mcp/http types). Test with talk_to_agent { endpointUrl }.

Key facts

• create_ai_agent auto-provisions: flow, AI Agent Job Node, REST endpoint
• If the target project was just auto-created and llmStatus is "unknown", immediately inspect other projects for reusable llm_model entries with connectionId before falling back to setup_llm.
• Cognigy connections are project-scoped. If you want to reuse LLMs from another project, import the required model set and their distinct connection resource(s) via manage_packages before testing the agent.
• For knowledge workflows, do not guess with the agent response model for Knowledge Search. Import the source project's exact Knowledge Search model into the target project before the first Knowledge AI settings attempt.
• create_tool auto-provisions: flow nodes for tools. Do NOT create tool nodes manually.
• Duplicate toolId values can cause empty or failed responses. Check the flow/tools before assuming the problem is the LLM or connection.
• Knowledge: Always attach knowledge stores as tools (via create_tool { toolType: "knowledge" } or knowledgeStoreReferenceId on create_ai_agent). Knowledge tools give the agent a dedicated search capability. Only attach to the persona (via update_ai_agent) if the user explicitly requests persona-level knowledge.
• Changing an EXISTING agent: the first such change in a session is HELD by the server and returns error: "backup_not_offered" without changing anything. Ask the user whether they want a backup, then call manage_snapshots { operation: "create", projectId, label } or { operation: "decline", projectId }, then retry the held call — see the snapshot-backups skill. This does NOT fire for an agent you created in this same session, so the build flow above is unaffected.
• Use same sessionId across talk_to_agent calls for multi-turn testing
• endpointUrl uses a different base URL (endpoint-*.cognigy.ai), not the API URL
• talk_to_agent sends in Cognigy Endpoint Test Mode by default, so test messages are not counted as billable; the response reports testMode and the regular endpointUrl. It never falls back to a billable send on its own. If a send fails, read _hints and check whether the message was processed before re-sending it (see the troubleshooting skill). Cognigy documents a fair-use limit of 600 test messages per hour (scope unspecified).