Using Agents

Chat with agents, manage conversations, provide feedback

Consumer Guide: Using Agents

This guide is for business users (consumers) who interact with AI agents through the Agent Portal. It covers how to find agents, start conversations, handle approvals, review history, and provide feedback.

Where to use agents: Agent Portal at http://localhost:3000 (log in as Consumer / Alice).

Table of Contents

• Accessing the Agent Portal
• The Agent Catalog
• Why You See Specific Agents
• Starting a Conversation
• Understanding Agent Responses
• Human-in-the-Loop (HITL) Approvals
• Conversation History
• Workflow Triggers
• Providing Feedback
• Account Settings

Accessing the Agent Portal

1. Open http://localhost:3000 in your browser.
2. You will be redirected to the login page.
3. Select the Consumer role card.
4. Optionally adjust your tenant and group memberships (for testing different access scenarios).
5. Click Login.
6. You are redirected to the Portal home page.

Navigation

The Portal sidebar provides access to all features:

The Agent Catalog

The Agent Catalog (/portal/agents) is your starting point for discovering agents. It shows all agents you are entitled to use, presented as cards in a searchable, filterable grid.

Browsing Agents

Each agent card displays:

• Agent Name -- The agent's display name (e.g., "Customer Support Bot").
• Description -- A brief explanation of what the agent does.
• Runtime Badge -- Pro-Code (blue) or n8n (pink), indicating the underlying runtime.
• Status Badge -- Active (green), Canary (yellow), or Draft (gray).
• Capabilities -- Tags showing what the agent can do (e.g., chat, knowledge-base, ticket-creation).

Filtering and Searching

Use the filter buttons at the top of the catalog to narrow results:

• All -- Show all agents.
• Pro-Code -- Show only Pro-Code runtime agents.
• n8n -- Show only n8n low-code agents.
• Active -- Show only fully deployed agents.
• Canary -- Show agents in canary deployment.
• Draft -- Show agents under development (only visible if you are an owner).

Use the search bar to search agents by name or description.

Why You See Specific Agents

Not all agents on the platform are visible to you. The platform uses entitlement-based filtering to show you only the agents you are authorized to use. This is determined by three factors:

1. Visibility Mode

2. Your Groups

Your IdP (Identity Provider) groups determine which restricted agents you can see. For example, if you belong to the hr-team group, you can see agents that include hr-team in their allowed groups.

In the mock environment, the default groups for the Consumer role are hr-team and all-staff. You can customize your groups at login time to test different access scenarios.

3. Your Role

Some agents restrict access by role (e.g., manager, director). Your platform role (consumer, builder, or admin) is checked against the agent's allowed roles.

What If You Cannot See an Agent?

If you expect to see an agent but it is not in your catalog:

• The agent may have restricted visibility, and your groups or role do not match.
• The agent may be in private or draft status.
• The agent may belong to a different tenant.
• Contact your platform administrator or the agent's builder to request access.

Starting a Conversation

From the Agent Catalog

1. Navigate to the Agent Catalog (/portal/agents).
2. Click on an agent card.
3. You are taken to the chat interface at /portal/chat/[agentId].

From the Chat Page Directly

1. Navigate to Chat (/portal/chat).
2. Use the agent selector or deep link to choose an agent.

The Chat Interface

The chat interface has three main areas:

Left Panel -- Conversation Sidebar:

• Lists your recent conversations with the current agent.
• Click a conversation to resume it.
• Click New Chat to start a fresh conversation.
• The sidebar can be collapsed for more screen space.

Center -- Message Area:

• Type your message in the input field at the bottom.
• Press Enter to send (or click the send button).
• Messages appear in a scrollable thread.
• The agent's responses stream in token-by-token, providing real-time feedback.
• Scroll up to review earlier messages. Auto-scroll pauses when you scroll up and resumes when you scroll back to the bottom.

Right Panel -- Agent Detail Panel (optional):

• Toggle the detail panel with the panel icon in the header.
• Shows agent metadata: name, description, version, runtime, capabilities, risk classification.
• Useful for understanding what the agent can do.

Sending Messages

1. Type your message in the input field at the bottom of the chat.
2. Press Enter to send the message.
3. The agent processes your message and responds with a streaming reply.
4. Wait for the response to complete before sending another message.

Tips for Effective Conversations

• Be specific. Instead of "Help me with my issue," try "I need help tracking order #12345 that has not arrived."
• Provide context. If the agent needs information, include it in your message rather than waiting to be asked.
• Use follow-up messages. Agents maintain conversation context. You can refer to earlier messages naturally.
• Ask the agent about its capabilities. Most agents can describe what they can do if you ask.

Understanding Agent Responses

Text Responses

Agent responses support rich formatting:

• Markdown rendering -- Headings, bold, italic, lists, links, and tables are rendered visually.
• Code blocks -- Code snippets appear with syntax highlighting and a copy button.
• Multi-part responses -- Some responses may arrive in multiple message bubbles, especially when the agent performs intermediate actions.

Tool Call Indicators

When an agent uses an external tool (such as searching a knowledge base or creating a ticket), you will see tool call indicators in the response:

• Tool name -- Which tool was invoked (e.g., "Knowledge Base Search").
• Status -- Whether the tool call succeeded (success) or failed (error).
• Duration -- How long the tool call took (e.g., 340ms).
• Input/Output -- Some responses show what was sent to the tool and what came back.

Tool call indicators appear inline with the agent's response, giving you visibility into what the agent did to generate its answer.

Confidence Indicators

Some agents include confidence scores with their responses. A high confidence score (e.g., 0.95) means the agent is highly certain about its answer. A lower score (e.g., 0.70) suggests the answer may be less reliable.

Token Usage

Each agent response includes token usage information:

• Input tokens -- How many tokens were sent to the LLM.
• Output tokens -- How many tokens were generated.
• Cost -- The estimated cost of the LLM call.

This information is shown for transparency and is primarily useful for understanding agent resource consumption.

Human-in-the-Loop (HITL) Approvals

Some agents are configured to request human approval before taking high-impact actions. When this happens, the agent pauses and creates an approval request that you (or a designated approver) must review.

When Does HITL Trigger?

HITL approval is triggered when:

• The agent attempts an action that exceeds its risk threshold (e.g., issuing a refund over $100).
• The agent tries to use a tool that requires approval (e.g., sending an email to an external recipient).
• The action has an impact classification that mandates human review (e.g., financial, irreversible, external-comms).

In-Chat Approvals

When an agent requests approval during a conversation, you will see an approval card inline in the chat. The card shows:

• Action description -- What the agent wants to do (e.g., "Issue full refund of $249.99 for order #12345").
• Risk score -- A numeric score (0--100) indicating the assessed risk.
• Impact type -- The category of impact (financial, irreversible, data, external-comms).
• Reasoning -- Why the agent believes this action is appropriate.
• Approve / Reject buttons -- Your action options.

Click Approve to let the agent proceed or Reject to block the action. You can optionally provide a reason with your decision.

The Approval Queue

All pending approvals across all agents are collected in the Approvals page (/portal/approvals).

The approval queue shows:

SLA Deadlines

Approvals have an SLA deadline (typically 1--3 hours from creation). If the deadline passes without action:

• The approval may auto-expire (depending on configuration).
• The agent's action is blocked.
• An escalation notification may be sent to the next person in the escalation chain.

Best Practices for Approvals

• Review approvals promptly to avoid blocking agent workflows.
• Read the agent's reasoning carefully before deciding.
• When rejecting, provide a reason so the agent (or builder) can understand why.
• If you see frequent false-positive escalations, provide feedback to the agent's builder.

Conversation History

The History page (/portal/history) provides access to all your past conversations across all agents.

Searching Past Conversations

• Search bar -- Search conversations by content, agent name, or keywords.
• Filters:
  • Agent -- Filter by a specific agent.
  • Date range -- Filter by start and end dates.
  • Status -- Filter by conversation status (active, completed, archived).

Reviewing Conversations

Click on a conversation to view the full message thread, including:

• All user messages and agent responses.
• Tool call details (what tools were invoked and their results).
• HITL approval decisions that occurred during the conversation.
• Timestamps for each message.

Exporting Conversations

You can export conversation transcripts for documentation or compliance purposes. Export formats may include JSON or plain text, depending on the platform configuration.

Workflow Triggers

The Workflows page (/portal/workflows) allows you to run pre-configured workflows without starting a conversation.

What Are Workflow Triggers?

Workflow triggers are pre-defined agent tasks that can be executed with specific parameters. They are useful for:

• Running recurring tasks (e.g., "Generate weekly sales report").
• Executing structured processes that require specific inputs.
• Triggering n8n workflows from the Portal (coming soon).

Running a Workflow

Note: The Portal Workflows page is temporarily disabled (coming soon).

1. Navigate to Workflows (/portal/workflows).
2. Browse available workflow triggers.
3. Click on a workflow to see its description and required parameters.
4. Fill in the parameters.
5. Click Run to execute the workflow.
6. Monitor the execution status on the same page.

Monitoring Execution Status

After triggering a workflow, you can see:

• Status -- running, completed, failed.
• Progress -- Which steps have been completed.
• Output -- The result of the workflow when it finishes.
• Duration -- How long the execution took.

Providing Feedback

Your feedback helps builders improve agent quality. The platform supports several feedback mechanisms.

Message-Level Feedback

After receiving an agent response, you can provide feedback directly in the chat:

• Thumbs up -- The response was helpful and accurate. This reinforces good behavior.
• Thumbs down -- The response was unhelpful, incorrect, or inappropriate. This flags issues.

Correction Feedback

When you give a thumbs down, you may be prompted to provide additional context:

• What was wrong with the response?
• What would the correct answer have been?
• Was the issue with factual accuracy, tone, relevance, or completeness?

The Feedback Dashboard

The Feedback page (/portal/feedback) shows:

• Your feedback history across all agents.
• Aggregate feedback statistics per agent.
• Trends in agent quality over time.

This information is shared with builders to help them improve their agents.

Account Settings

The Settings page (/portal/settings) lets you manage your account preferences.

Profile Information

View your account details:

• Name -- Your display name.
• Email -- Your email address.
• Role -- Your platform role (consumer, builder, or admin).
• Groups -- Your IdP group memberships (determines which agents you can see).
• Tenant -- Your organization tenant.
• IdP Source -- Your identity provider (e.g., Keycloak, Azure AD).

Active Sessions

Manage your active sessions:

• View all currently active sessions (browser, device, IP address).
• Sign out all sessions to terminate all active sessions across all devices.

Notification Preferences

Configure how you receive notifications:

• Approval notifications -- When a new HITL approval request arrives.
• Agent response notifications -- When a long-running agent task completes.
• System notifications -- Platform announcements and maintenance windows.

Notification channels may include:

• In-app notifications (bell icon in the header).
• Email notifications (optional).

Frequently Asked Questions

Q: Can I use multiple agents in a single conversation?

Currently, each conversation is with a single agent. However, agents may delegate tasks to other agents behind the scenes using the A2A (Agent-to-Agent) protocol. You interact with one agent, but it may collaborate with others to fulfill your request.

Q: Why did the agent stop responding?

This can happen if:

• The agent is waiting for a HITL approval (check the Approvals page).
• The agent encountered an error (a message will indicate this).
• There is a network issue (refresh the page and try again).

Q: Can I delete a conversation?

Conversation deletion policies are controlled by the platform administrator. Contact your admin if you need to remove a conversation.

Q: How do I request access to an agent I cannot see?

Contact your platform administrator or the agent's builder. They can add your group, role, or user ID to the agent's entitlements. Alternatively, the agent can be changed to public visibility.

Q: Is my conversation data private?

Your conversations are scoped to your tenant and user ID. Other users in your tenant cannot see your conversations. Platform administrators and the agent's builders may have access to conversation data for debugging and improvement purposes, subject to your tenant's data governance policies.

Related Documentation

• Getting Started Guide -- Initial setup and environment configuration
• Registering Agents Guide -- How builders create the agents you use
• Builder Access Control Guide -- How agent visibility is configured
• Troubleshooting Guide -- Resolving common issues