Add customer support email agent using Commune

[shanjairaj7]

What this notebook covers

This notebook shows how to build a customer support email agent using the OpenAI Python SDK with GPT-4o function calling and Commune — a programmable email and SMS API built for AI agents.

The notebook lives in examples/agents_sdk/ because it demonstrates a complete, production-oriented agentic workflow: multiple tools, multi-turn reasoning, error handling, and a polling loop suitable for deployment.

Use case

A SaaS company points a Commune inbox at their support address. The agent reads new tickets, classifies them (billing / technical / feature-request), drafts empathetic replies, sends them via the Commune API, and SMS-escalates P0 issues to an on-call phone number — all without human intervention.

What readers learn

1. Function-calling schema — how to define Commune's read/search/send/SMS operations in OpenAI's {"type": "function", ...} format
2. Correct tool_calls loop — proper handling of finish_reason == "tool_calls", executing each tool_call, and returning {"role": "tool", ...} messages
3. Multi-step triage — agent chains read_inbox → get_email → send_email across multiple turns autonomously
4. Production patterns — exponential-backoff polling loop and a webhook handler snippet for Flask

Why it's valuable

Support inbox automation is one of the highest-ROI use cases for function-calling agents but is underrepresented in the cookbook relative to its real-world prevalence. This recipe gives developers a complete, working starting point that handles the email infrastructure (via Commune) so the focus stays on the agent logic.

Technical details

• Uses openai Python SDK directly — no LangChain, no framework
• Uses commune-mail Python package (pip install commune-mail)
• Model: gpt-4o (also compatible with gpt-4o-mini for cost-sensitive deployments)
• All tool calls hit the real Commune API — no mock data
• Includes SMS escalation via commune_client.sms.send()

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f3d3822543

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

Register new notebook in registry.yaml

This commit adds a new notebook at examples/agents_sdk/email_agent_with_commune.ipynb, but there is no corresponding entry for that path in registry.yaml (repo search shows no match). Per this repo’s contribution rules in AGENTS.md, new content must be registered so it is published; without that metadata, this example will not be included by the site generator and is effectively invisible.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Guard JSON parsing of tool arguments

execute_tool_call calls json.loads(tool_call.function.arguments) before entering the try block, so malformed tool arguments raise JSONDecodeError and terminate the run instead of being returned as a tool-level error. In practice, one bad tool-call payload can crash the entire support workflow during multi-turn processing.

Useful? React with 👍 / 👎.

[shanjairaj7]

Addressed the two Codex review items:

P0 — registry.yaml (commit 1dd0a5a): Added the notebook entry to registry.yaml with path, slug, description, date, and agents-sdk / function-calling / email / tool-use tags.

P2 — JSON parsing guard (commit 8184188): Moved json.loads(tool_call.function.arguments) inside the try block and added an explicit json.JSONDecodeError catch clause that returns a tool-level error string. A malformed payload from the model no longer aborts the agent run — it degrades gracefully and the agent can decide how to handle the failed tool result.