Understanding Agent Pings & Notifications

Note: Refer to screenshots throughout this guide for visual clarity.

Portal One agents can get your attention when they need your input or have an update by sending you a Notification. These Notifications appear in a dedicated "Notifications" view, prompting you to check the originating conversation with the agent.

This system is designed to draw you back to the relevant chat when an agent requires clarification, has an update, or needs a decision that doesn't involve a formal tool approval. It's distinct from Action Approvals (covered in the next guide), which are specifically for authorizing an agent's use of MCP tools.

Why Agents Notify You

Agents will notify you (or specific user roles) when they need to:

• Request Clarification: If an instruction is ambiguous, an agent can ping you to check the conversation for its question (e.g., the agent might ask in the chat, "Okay, @Owner, which report are you referring to?").
• Signal Important Updates: Notify you that a status update is available in the conversation.
• Prompt Non-Tool-Based Decisions: Alert you that your input is needed on a matter discussed in the chat.
• Indicate Readiness for Next Steps: Let you know it has completed a part of a task and is awaiting your guidance in the conversation.

How Agents Trigger Notifications

1. Configuring Agent Contacts:
   For an agent to ping a user or role, it must first be configured with "contacts": Adding a contact adds a special tool to the agent which allows it to generate a @mention for the assigned contact.
   1. Navigate to the specific agent's Details page.
   2. Select the "Config" tab.
   3. Scroll down to the "Contacts" list card.
   4. Choose a contact from the dropdown menu (e.g., a specific user, or a role like @Owner or @Manager).
   5. Click the "Add" button.
2. The Agent's Action in the Conversation:
   The agent will choose to use the tool which will generate a @mention for the contact. The @mention then triggers a message from any non-human contacts, or will create an alert for any human controlled contacts.

Receiving and Viewing Your Notifications

1. Notification Indicator:
   When an agent pings you, a badge with a number will appear next to the "Notifications" link in the main navigation pane on the left. This indicates you have items needing your attention.
2. Navigating to the "Notifications" View:
   Click on the "Notifications" link in the navigation pane to open the Notifications view.
3. Understanding the "Notifications" View:
   The "Notifications" view displays a list of recent alerts. Each notification item typically shows:
   • The originating agent's avatar and name (e.g., "Rayne").
   • A brief message "[Agent Name] pinged you X [time unit] ago".
   • An "X" (close/dismiss) button in the corner of the item to remove it from this list.

Responding to Agent Notifications

The "Notifications" view itself is not for direct replies. To respond or act on an agent's ping:

1. Identify the Notification: Note which agent pinged you from the "Notifications" list.
2. Navigate to the Conversation:
   • Clicking on the notification item should take you to the originating conversation.
3. Review & Respond in Chat: Read the agent's latest messages in the conversation thread to understand why it notified you. Type your response directly in the chat input field and send it as you normally would.

Notification Lifecycle: After Viewing or Dismissing

• Clicking the "X" on a notification item in the "Notifications" view will dismiss it from this list.
• The actual interaction (reading the agent's full message and your reply) happens within the conversation view with that agent. Dismissing the notification does not affect the conversation itself.

Example Scenario: Agent Pings for Clarification

Let's see a simple example:

1. Setup:
   • You have an agent named "Research Bot."
   • You've configured "Research Bot" with @Owner as a contact.
2. Interaction:
   • You (as the Owner) tell Research Bot in its chat: "Find recent news about AI advancements."
   • Research Bot needs additional clarification from you so he uses the hey_owner tool that he was given automatically when Owner was added to his contacts list.
   • The tool causes a notification to appear on the dashboard of any user with the Owner role in the workspace.
   • You click on the notification and it takes you to the relevant conversation where you quickly catch up and respond "How can I help?".
   • The notification is dismissed and Research Bot asks: "Could you specify if you're interested in a particular area of AI, like NLP, computer vision, or robotics?"
3. Your Experience:
   • You see a notification badge appear next to "Notifications."
   • You click on "Notifications" and see an item: "Research Bot pinged you a moment ago."
   • You click on this notification item (or manually navigate to your conversation with Research Bot).
   • In the chat with Research Bot, you see its full question.
   • You type your reply in the chat: "Let's focus on NLP advancements." and send it.
   • Research Bot now has your clarification and continues its task.
   • You can dismiss the "Research Bot pinged you..." item from the Notifications view at any time by clicking the "X".

Quick Reference: Agent Pings & Notifications

• Configure Contacts: Agent Details → Config tab → Contacts card → Add contact. (This enables agents to ping them).
• Agent Action: Agent uses ask_owner tool which triggers a notification, and then posts message/question in conversation.
• Receive Pings: Notification badge on "Notifications" link in navigation.
• View Pings: Click "Notifications" link to see who pinged you.
• Respond: Navigate to the originating conversation view with the agent and reply there.
• Dismiss Notification: Click "X" on the notification item in the "Notifications" view.

Glossary

• Ping: An alert generated by an agent (via a tool call to a configured contact) to draw a user's attention to new activity or a query in the agent's conversation thread.
• Notification: The item that appears in the "Notifications" view, indicating an agent has pinged you.
• Contacts (Agent): Users or roles (like @Owner, @Manager) that an agent is configured to be able to ping.
• Conversation View: The main chat interface where you interact directly with an agent.

Key Takeaways

• Attention Signal: Notifications are designed to let you know when an agent needs your attention in its specific conversation thread.
• Centralized Alerts: The "Notifications" view gives you a quick list of agents that have recently pinged you.
• Interaction in Context: All detailed messages and your replies happen within the agent's main conversation view, keeping interactions contextual.
• Distinct from Tool Approvals: Remember, this is for drawing attention to conversational needs, while "Action Approvals" (next guide) are for authorizing agent tool usage.

Understanding how to use agent pings and the "Notifications" view will help you stay responsive to your agents and ensure they get the guidance they need efficiently.