Outlook & Calendar

Empower your agents to manage emails and calendars directly through Microsoft Outlook.

This guide will walk you through setting up your Azure Active Directory (AD) application, configuring the SVAHNAR tool, and authenticating your user.

💡 Core Concepts

To configure this tool effectively, you need to understand the underlying capabilities and the authentication flow.

1. What can this tool do?

The Outlook tool interacts with the Microsoft Graph API to perform common mailbox and calendar actions. Your agent can call the following operations:

Operation	Description
list_messages	List the latest email messages in the user's inbox (supports paging/sorting).
get_message	Retrieve details of a single email message by message ID.
important_mail	Retrieve messages flagged as high importance.
mail_from_address	Retrieve email messages from a specific sender address.
content_search_in_mail	Perform a free-text search across mailbox messages.
messages_today	Retrieve all emails received today dynamically.
unread_messages	Retrieve all unread emails in the user's inbox.
send_mail	Send a new email (supports plain text or HTML bodies).
reply_to_message	Reply to an existing email message by ID.
forward_message	Forward an existing email message to other recipients.
create_draft	Create a new draft email in the user's mailbox.
delete_message	Delete an email message by ID.
mark_as_read	Mark an email message as read by ID.
flag_message	Flag/star an email message by ID for follow-up.
list_folders	List all mail folders in the user's mailbox.
meetings_today	Retrieve all calendar events and meetings scheduled for today dynamically.
meetings_tomorrow	Retrieve all calendar events and meetings scheduled for tomorrow dynamically.
next_meeting	Retrieve the very next upcoming calendar meeting/event.
event_for_week	Retrieve calendar events for a specific date range (or the next 7 days by default).
all_event	Retrieve all upcoming calendar events (subject, organizer, start, end, location, etc.).
all_calendar	List all calendar folders associated with the user's account.
schedule_meet	Create calendar events/meetings and invite attendees (supports locations and descriptions).
delete_event	Delete a calendar event by ID.

2. Authentication

This tool uses OAuth 2.0

• First Run: You must explicitly click Authenticate in the tool configuration UI to generate the initial tokens. (check step 4)
• Maintenance: Tokens may expire approximately every 90 days. If the tool stops working, simply re-run the Authenticate flow.

---

⚙️ Configuration Steps

Follow these steps to connect your Microsoft Outlook tenant.

Create Azure App Registration

1. Log in to the Azure Portal.
2. Navigate to Azure Active Directory -> App registrations -> New registration.
3. Register your app and note the Application (client) ID and Directory (tenant) ID.

Generate Client Secret

1. In your App Registration, go to Certificates & secrets.
2. Click New client secret.
3. Crucial: Copy the Value immediately. You will not be able to see it again.

Configure API Permissions

1. Go to API permissions -> Add a permission -> Microsoft Graph -> Delegated permissions.
2. Add the following permissions:

• Mail.Read (or Mail.ReadWrite)
• Mail.Send
• Calendars.Read (or Calendars.ReadWrite)
• offline_access (Required for refresh tokens)

3. If your tenant requires it, click Grant admin consent.

Configure & Authenticate in SVAHNAR

1. Open your SVAHNAR Agent Configuration.
2. Add the Outlook tool and enter your Azure credentials:

• tenant_id
• client_id
• client_secret

3. Save the configuration.
4. Action Required: Click the Authenticate button in the tool UI. This will launch a pop-up to log in with your Microsoft account and store the secure tokens in your Keyvault.

---

📚 Practical Recipes (Examples)

Recipe 1: Executive Assistant Agent

Use Case: An agent that manages your schedule and highlights important emails.

create_vertical_agent_network:
  agent-1:
    agent_name: executive_assistant
    LLM_config:
        params:
          model: gpt-4o
    tools:
      tool_assigned:
        - name: Outlook
          config:
            # Azure AD Credentials
            tennant_id: ${tenant_id}
            client_id: ${client_id}
            client_secret: ${client_secret}
    agent_function:
      - You are an executive assistant.
      - Check my calendar for the week using 'event_for_week'.
      - Scan for 'important_mail' and summarize urgent items.
      - If I ask to schedule a meeting, use 'schedule_meet' and ensure all details (subject, time, attendees) are correct before confirming.
    incoming_edge:
      - Start
    outgoing_edge: []

💡 Tip: SVAHNAR Key Vault

For security, never hardcode your Client Secret in plain text files. Use SVAHNAR Key Vault (like ${client_secret}).

---

🚑 Troubleshooting

• "Token not found" or Authentication Errors

  • Ensure you have clicked the Authenticate button in the UI at least once.
  • Check if 90 days have passed since the last authentication; if so, re-authenticate.

• Permission Denied (403)

  • Verify that you added the correct Delegated permissions (Mail.Read, Mail.Send, etc.) in the Azure Portal.
  • Ensure you clicked Grant admin consent if your organization requires it.