# Agent Creation > Use when the user wants to build, create, or set up a new Cognigy AI Agent from scratch — covers listing projects, ensuring an LLM exists, creating the agent, testing it, and refining persona/job fields. - Skill: `cognigy/agent-creation` (Agent Skill) - Install (CLI): `npx skillmds@latest add cognigy/agent-creation` - Raw SKILL.md: https://api.skillmd.com/api/skills/cognigy/agent-creation/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: Cognigy (https://skillmd.com/u/cognigy) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/cognigy/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: "" } } 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) | Field | Purpose | Example | | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | | name | Agent display name | "Acme Support Bot" | | description | **Agent persona** — defines who the agent is, its personality, tone, and high-level behavior. This is the primary field for shaping agent identity. | "You are a friendly customer support agent for Acme Corp. You speak in a professional yet warm tone..." | | instructions | **Agent instructions** — high-level guidance and constraints (up to 1000 chars). Use for guardrails and policies that apply regardless of the job. | "Never share internal pricing. Always verify customer identity before account changes." | ### Job-level fields (jobConfig — how the agent performs its job) | Field | Purpose | Example | | ---------------------- | --------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | jobName | **Job title** — the role the agent is performing | "Customer Support Specialist" | | jobDescription | **Job description** — detailed description of responsibilities, scope, and expertise areas for this job | "Handle customer inquiries about orders, returns, and product information. Escalate billing disputes to human agents." | | jobInstructions | **Job instructions** — specific behavioral rules, step-by-step procedures, and output format requirements for the job | "1. Greet the customer. 2. Ask for their order number. 3. Look up the order using the search tool..." | | llmProviderReferenceId | Which LLM the agent uses (from setup_llm or list_resources { resourceType: "llm_model" }) | "abc-123-def-456" | | temperature | LLM temperature (0-1). Lower = more deterministic, higher = more creative. Default: 0.7 | 0.3 | | maxTokens | Max tokens for LLM response (100-8000). Default: 4000 | 2000 | ### 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).