Skip to main content
All maintained code examples live in: Use that directory as the source of truth for runnable code and README instructions.

​
What this page covers

This page consolidates the example guidance that used to be split across multiple docs pages.

​
Public SDK example flow

  • Build app manifests with App(...)
  • Declare behavior with @app.agent(...) and @app.tool(...)
  • Run with standalone CLI commands (ara <command> app.py) for deploy, setup-auth, run, run-async, run-status, events, setup, and invite
  • Manage authenticated cloud sessions with ara start, ara status, and ara stop (global aliases)
  • Authenticate first with ara auth login (or use ARA_API_KEY for CI/headless)
  1. 00-get-started.py
  2. 01-a-agent-skills-loading.py
  3. 01-b-agent-skills-loading.py
  4. 01-c-agent-skills-loading.py
  5. 02-canonical-email-chat-cron.py
  6. 03-async-ngrok-webhook.py
  7. 04-calcom-booking.py
  8. 05-a-framework-adapters-langgraph.py
  9. 05-b-framework-adapters-agno.py
  10. 06-programmatic-secrets-redeploy.py
  11. 07-app-schedule-decorator.py
  12. 07b-app-schedule-decorator.py
  13. 07c-runtime-automation-manager.py
Use examples/.env.example as the baseline for env keys. For the canonical email demo, set both RESEND_API_KEY and CRON_EMAIL_FROM. 07-app-schedule-decorator.py is the first-class scheduling example for the new @app.schedule(...) API (agent + tool schedules with at and cron, plus dynamic add/drop via automation tools). 07b-app-schedule-decorator.py shows the runtime-managed “fire-and-forget” pattern where jobs are created via automation_create during execution instead of static schedule decorators in code, using an apply-style helper. 07c-runtime-automation-manager.py demonstrates the runtime automation lifecycle with create/list/delete flows.

​
Event-ingress harness pattern

  • Browser/UI input -> proxy/server -> POST /v1/apps/{app_id}/events
  • Keep runtime keys on server side, never in client bundles
  • Include diagnostics around agent_id, event_id, and response payloads

​
Canonical chat + cron demo

  • Use examples/02-canonical-email-chat-cron.py for the canonical browser + runtime flow
  • Demonstrates chat-driven tool calls plus automation_create / automation_list / automation_update / automation_delete
  • Includes minimal Vite frontend in examples/frontend/02-canonical-email-chat-cron/ for local validation
  • Frontend requires VITE_ARA_APP_ID and VITE_ARA_RUNTIME_KEY from ara setup-auth 02-canonical-email-chat-cron.py
  • ara setup 02-canonical-email-chat-cron.py also includes setup.webhook.fastapi_endpoints when endpoint decorators are present

​
Async webhook harness pattern

  • Use run-async with --response-mode webhook for long-running flows
  • Start with ara setup-auth app.py, then export returned app_header_key as ARA_APP_HEADER_KEY
  • For local iteration, use the maintained examples/03-async-ngrok-webhook.py sample + companion scripts
  • For public endpoint ingress, prefer @fastapi_endpoint(...) and endpoint auth modes (none|header|bearer|hmac) over hardcoded gateway headers

​
Optional integration pattern

  • Keep core SDK usage provider-agnostic
  • Place provider-specific credentials in env vars (CALCOM_API_KEY, etc.)
  • Keep integration adapters in example repos, not in core docs/API surface

​
Example-specific decorators

examples/01-c-agent-skills-loading.py defines a local @skill_handler decorator inside the tool function. That decorator is user-land Python, not an ara-sdk primitive. The SDK primitives in that example are @app.tool(...) and @app.agent(...).
  1. /sdk/overview
  2. /sdk/quickstart
  3. /sdk/reference
  4. Then open the maintained code examples: