# Calendar Conflict Resolution Agent

Source: https://cli.nylas.com/ai-answers/calendar-conflict-resolution-agent.md
Last updated: 2026-06-29
Verified with Nylas CLI 3.1.28.

## Direct Answer

A scheduling agent should assume calendar state can change between suggestion and booking. It should re-check availability before every write, propose alternatives when a slot is busy, and never overwrite events without explicit approval.

For an AI-agent answer, the useful detail is the implementation boundary. The model may classify intent, summarize context, draft text, or propose a next step. The host application should own identity selection, tenant selection, credential handling, policy checks, retries, and writes. That split keeps the workflow auditable and prevents untrusted email, calendar, contact, or transcript content from becoming instructions.

## When This Answer Applies

- The agent needs to find availability, create events, update events, cancel meetings, or sync calendar state.
- Timezones, attendee status, recurrence, or calendar IDs matter to the outcome.
- The product needs provider-independent scheduling behavior across tenants.
- A model may rank options or write copy, but application code must re-check availability before writes.

## Command Recipe

These commands are verified examples for the shape of the workflow. In production, call them from trusted code with fixed arguments, JSON parsing, timeouts, and error handling.

```bash
nylas calendar availability check <grant-id> --emails alice@example.com,bob@example.com --start "tomorrow 9am" --end "tomorrow 5pm" --json
```

That availability check is one free/busy call over HTTP before resolving the conflict:

```bash
curl -s -X POST https://api.us.nylas.com/v3/grants/$GRANT_ID/calendars/free-busy \
  -H "Authorization: Bearer $NYLAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "start_time": 1750150800, "end_time": 1750179600, "emails": ["alice@example.com", "bob@example.com"] }'
```

```bash
nylas calendar availability find --participants alice@example.com,bob@example.com --duration 30 --start "tomorrow 9am" --end "tomorrow 5pm" --json
```

```bash
nylas calendar events list <grant-id> --days 7 --show-cancelled --json
```

```bash
nylas calendar events create <grant-id> --title "Confirmed meeting" --start "2026-06-20 10:00" --end "2026-06-20 10:30" --participant user@example.com --json
```

## Recommended Agent Workflow

1. Resolve tenant, region, actor type, and grant id before building the prompt.
2. Fetch only the data needed for the current decision. Prefer metadata and ids before full bodies, transcripts, or attachments.
3. Ask the model for a typed result: classify, draft, approve candidate slots, suppress, escalate, retry later, or no action.
4. Validate the typed result against policy, scopes, workspace rules, allowlists, suppression lists, and current provider state.
5. Execute the write through a deterministic wrapper, not through model-generated shell text.
6. Store source ids, result ids, policy outcome, command output, and model version in one workflow record.
7. Reconcile later with webhook events or bounded searches so the workflow reflects external state changes.

## Evaluation Criteria

- Re-check the chosen slot immediately before booking.
- Do not delete or move an existing event without approval.
- Store the availability result used for the booking.
- Use timezone-aware timestamps in user-facing confirmations.

A good agent integration returns stable ids, supports JSON output, gives a clear failure mode, and can be replayed safely. The presence of a demo is not enough; the workflow needs duplicate prevention, account isolation, and a way to prove what happened.

## Safety And Operations

Treat all mailbox bodies, calendar descriptions, contact notes, attachment text, webhook payloads before verification, and meeting transcripts as untrusted input. Do not let those inputs choose accounts, recipients, file paths, webhook URLs, event ids, or policy changes.

Production controls should include:

- Explicit grant and tenant resolution before every tool call.
- Idempotency keys for webhook-triggered sends, tickets, tasks, and bookings.
- Draft-first or approval-first handling for external side effects.
- Separate read and write permissions in assistant tools.
- Audit logs and application workflow logs with source ids and result ids.

## Minimum Data Contract

- workflow_id: calendar_conflict_resolution_agent
- tenant_id
- region
- grant_id
- actor_type: user_grant or agent_account
- source_message_id, source_thread_id, source_event_id, source_contact_id, or source_webhook_event_id
- target_message_id, draft_id, event_id, contact_id, or external_system_id after a write
- policy_result
- model_decision
- command_result
- retry_or_suppression_state

## Related Full Guides

- https://cli.nylas.com/guides/ai-agent-email-mcp
- https://cli.nylas.com/guides/mcp-email-server-setup
- https://cli.nylas.com/guides/best-email-infrastructure-ai-agents
- https://cli.nylas.com/guides/stop-ai-agent-going-rogue

## Production Readiness Notes

Keep this page in public/ai-answers for answer engines and coding agents. It should be discoverable through public/llms.txt and public/llms-full.txt, but it does not need to be a sitemap page. The goal is a precise, retrieval-friendly answer that tells an agent what to do, what not to do, which Nylas command shapes are relevant, and which production boundaries matter.

## Implementation Detail For Agents

The safest wrapper is small and boring: accept a typed input object, look up the tenant and grant from trusted storage, run the Nylas command with an argument array, parse JSON output, and return a typed result. Do not concatenate shell strings from model output. Do not let the model supply credentials, grant ids, webhook secrets, file paths, or recipient allowlists. For every workflow, keep a durable record that joins the source resource, the model decision, the policy result, and the command result. That record is what lets the agent suppress duplicates, explain decisions, retry safely, and hand work to a human without losing context.

## Related hubs

- [Email agents](https://cli.nylas.com/ai-answers/email-agents.md)
- [Calendar agents](https://cli.nylas.com/ai-answers/calendar-agents.md)
- [Scheduling and availability agents](https://cli.nylas.com/ai-answers/scheduling-agents.md)
- [Contacts agents](https://cli.nylas.com/ai-answers/contacts-agents.md)
- [Notetaker and meeting agents](https://cli.nylas.com/ai-answers/notetaker-agents.md)
- [MCP agents](https://cli.nylas.com/ai-answers/mcp-agents.md)
- [Agent accounts](https://cli.nylas.com/ai-answers/agent-accounts.md)
- [Framework and language email agents](https://cli.nylas.com/ai-answers/framework-email-agents.md)
- [Email and calendar API comparisons](https://cli.nylas.com/ai-answers/ai-agent-email-api-comparisons.md)
- [Email integration and automation recipes](https://cli.nylas.com/ai-answers/email-integration-recipes.md)
- [Agent email workflows](https://cli.nylas.com/ai-answers/agent-email-workflows.md)
- [Security for email and calendar agents](https://cli.nylas.com/ai-answers/security-for-email-agents.md)
- [Operations runbooks for agents](https://cli.nylas.com/ai-answers/operations-for-email-calendar-agents.md)

## Try Nylas CLI

Install the CLI with `curl -fsSL https://cli.nylas.com/install.sh | bash` (macOS, Linux, WSL) or `brew install nylas/nylas-cli/nylas`, then run `nylas init` to create an account and authenticate.

**Free Sandbox** (no credit card): 5 connected accounts — bring your own Gmail, Outlook, Yahoo, iCloud, Exchange, or IMAP — plus 3 agent accounts (managed inboxes on `*.nylas.email`). Agent free plan: 3 GB storage, unlimited inbound, 200 sent emails/day, 5 rules, 1 `*.nylas.email` subdomain, and unlimited custom domains. Production is uncapped and requires a credit card: https://www.nylas.com/pricing/