Configuring Agents

Agents are configured within a blueprint. Each agent defines an AI persona with specific identity, behavior, and capabilities.

Creating an agent

To create an agent, navigate to a blueprint and add an agent with the following properties:

Identity

• Name — the display name users see in conversations (for example, "Support Agent" or "Sales Assistant")
• Description — a detailed description of the agent's role and behavior. This text is used as system instructions for the LLM, so it directly shapes how the agent responds. Write it as you would a system prompt: clear, specific, and focused.
• Avatar — an image that represents the agent visually
• Color — an accent color used in the conversation UI

Behavior

• Default flow — the automation flow triggered when a conversation starts or a message is received. This flow defines the agent's step-by-step logic for handling interactions. See Flows for details.
• Query suggestions — an array of pre-written questions or prompts shown to users at the beginning of a conversation. These help guide users toward topics the agent handles well.

Knowledge

• Knowledge base — a search index containing documents the agent can reference. When the assistant engine processes a query, it retrieves relevant content from this index and includes it in the LLM context. See Knowledge Base for details.

Flags

• Service agent — set to true for background agents that are not user-facing. Service agents can execute operations and participate in system flows without appearing in the user-facing agent list.

Agent identifiers

Each agent has a unique identifier scoped to its blueprint:

{blueprintName}-{blueprintUID}@{major}.{minor}/agents/{agentSlug}-{agentUID}

For example: [email protected]/agents/support-agent-uagt_xyz

This identifier is used to reference the agent in API calls, flow configurations, and channel settings.

Service accounts

When an app containing agents is installed in an organization, the platform automatically creates a service account for each agent. These accounts:

• Are registered in the identity provider (Zitadel)
• Are added as members of the organization
• Allow the agent to post messages, execute actions, and operate within the permission system
• Have the agent's name and avatar as their profile

You do not need to manage service accounts manually — they are created and updated automatically during app installation and blueprint updates.

Writing effective agent descriptions

The agent's description serves as the system prompt for all LLM interactions. Writing a clear, specific description is the most impactful way to shape the agent's behavior.

Effective descriptions include:

• Role definition — what the agent is and what it does ("You are a customer support agent for a SaaS product.")
• Behavioral guidelines — tone, length, and style ("Respond concisely. Use a professional but approachable tone.")
• Scope boundaries — what the agent should and shouldn't do ("Only answer questions about the product. For billing issues, transfer to a human agent.")
• Context about the domain — key facts the agent should know ("Our product supports three pricing tiers: Free, Pro, and Enterprise.")

Related concepts

• Knowledge Base — adding documents for RAG retrieval
• Assistant Execution — how the AI engine uses agent configuration
• Flows — building the automation logic agents use
• Conversations — the messaging system agents interact through