Service 2

Magellan Agent

Autonomous email-processing agent. Monitors an O365 inbox for hotel contract PDFs, routes them through the full verification-to-booking pipeline via OpenAI function calling, and replies to senders with the results. Conversation state and stage transitions live in PostgreSQL.

Poller lifecycle

Step 1

Poll inbox

O365 fetch since last checkpoint

Step 2

Filter & dedup

PDF present + not already processed

Step 3

Run agent

OpenAI tool-calling loop

Step 4

Reply & record

Email reply + Postgres write

Stage tracking

Every tool call advances the conversation. The latest tool call in a turn wins — terminal stages are reached after a successful dupload or blockload.

verification

verify-contract

matching

event-match

terminal · dupload

live rates pushed

terminal · blockload

block rates pushed

failed

tool error or rejection

Modules

app/clients/email.py

O365 integration. fetch_new_emails, download_pdf_attachments, reply_to_email, delete_email, _has_pdf_attachment. Includes safe OData escaping and account reset on stale auth.

app/agent/processor.py

OpenAI conversation manager. process_email drives the tool-call loop. _strip_failed_tool_rounds compacts failed assistant + tool rounds with summaries to stay inside the context window.

app/agent/conversation.py

ConversationStore — PostgreSQL-backed history, stage transitions, sender allowlists, action scheduling, approval workflow, dedup, attachment caching. Auto-reconnect on auth/connection errors. Credentials via AWS Secrets Manager when rds_secret_arn is set.

Resilience

Why it does not fall over

The agent processor compacts fully-failed assistant + tool rounds into short summaries before sending the next turn to OpenAI. This keeps the context window stable across long conversations and means a single bad tool call cannot poison downstream reasoning. The ConversationStore wraps every database call in an _auto_reconnect decorator that retries on auth and connection errors, then rebuilds the pool with fresh credentials.