# Datagran agent guide

> Datagran spans marketing analytics and creative, voice, CRM, Inbox, connections, Calendar, Groovy, Intelligence and operational evidence.

## How to start
1. Read `/llms.txt` for a compact index and `/.well-known/datagran-products.json` for structured discovery.
2. Read only the relevant `/docs/products/{id}.md` pages.
   If a page lists product-owned discovery URLs, first verify a live anonymous 200 response and content type. Home has not checked their deployment; a 404 is not a grant or a working API.
3. For a new user, open [Sign up](/signup) and let the user complete identity, credentials and any provider consent. Then authenticate and determine the exact tenant and project; do not assume a shared account grants client access.
   If signup reports an existing account or an uncertain outcome, have the user try [Sign in](/login) with that email before submitting signup again. Do not blindly retry account creation.
4. With the current browser session, call `GET /api/platform/agent-workspaces`. If it lists more than one tenant or project, ask the user to select the exact scope. The default project is only a UI hint.
5. For the selected tenant, call `GET /api/platform/agent-catalog?tenant_id={tenant_id}` with its exact tenant ID. Check the requested products, available capabilities and the actor's role for the selected project. A listed transport is not runtime readiness.
6. For the selected project, call `GET /api/platform/project-status?tenant_id={tenant_id}&project_id={project_id}` with both exact IDs. Read its saved product roles, assigned connections and permission-filtered next reads. Its provider and deployment readiness values remain unverified.
   If connection setup needs inspection and the current actor is a tenant administrator or Datagran superadmin, call `GET /api/platform/agent-connection-status?tenant_id={tenant_id}&project_id={project_id}`. Other actors must ask an administrator. This read reports saved Home topology only; it does not check a provider or Calendar agent grant.
7. A new signup includes Home/Intelligence, not automatic CRM, Inbox or Voice access. If a requested product is disabled, have a tenant administrator use Home's reviewed setup flow. `product_setup_not_configured` requires Datagran support; a saved entitlement or product badge is not runtime readiness.
   Open [Products](/dashboard/products) after selecting the tenant and project in Home. A tenant administrator can [enable the product](/admin/products) and [assign a project role](/admin/product-access). These are browser pages with separate access checks, not general agent write APIs.
   For Inbox, a tenant administrator can [connect Instagram or Messenger](/connections#social-messaging) and must choose the exact project in the form. An Inbox product administrator without tenant administration can open Inbox but must ask the tenant administrator to connect the channel. A saved channel is not proof of delivery.
   For email outreach, a tenant administrator connects Gmail / Google Workspace or Outlook / Microsoft 365 in the Email section of [Connections](/connections). Confirm the sender, exact project and ready send/receive permissions. An Inbox project administrator follows Inbox → Automations → New automation → Create a personal email automation. This opens Audience, Message and Launch; the general editor's Email channel is a different workflow. Use the [input checklist](https://api.agents.datagran.io/v1/inbox/docs.md#gather-the-inputs) and [readiness checks](https://api.agents.datagran.io/v1/inbox/docs.md#check-readiness-and-resolve-blockers). Research has its own paid approval and may start before mailbox setup; sending requires a ready mailbox and separately reviewed recipients, copy and budget. Connecting a mailbox does not send a message.
8. Check connection assignment, product authorization, runtime readiness and any per-operation confirmation before acting.
9. Verify the outcome using the returned receipt or status; report unavailable and uncertain states explicitly.

## Optional delegated Home reads
A registered AI client can start OAuth from [Home's protected-resource metadata](https://home.datagran.io/.well-known/oauth-protected-resource/api/mcp). Check that metadata and [the authorization-server document](https://home.datagran.io/.well-known/oauth-authorization-server) before connecting to https://home.datagran.io/api/mcp. The user must consent to exact tenant and project access.
Home's delegated tools list workspaces, read the selected tenant catalog and read the selected project status. They cannot create ads, agents, leads, follow-ups or bookings. Consent, current access and the requested scope are checked on every tool call. Do not copy browser cookies into a client or treat a successful connection as product readiness.

## Safety rules
- Public discovery is not authorization. Sign in, use GET /api/platform/agent-workspaces, select the exact tenant and project, then read the tenant and project status before using a tool.
- Do not use a disabled product or infer a connection, grant, deployed feature or runtime readiness from this catalog.
- Ask for explicit human approval before sending messages, buying a number, creating an ad draft, changing a live workflow, or booking a meeting. Respect the exact confirmation contract of each operation.
- Never request or display provider secrets, private customer data, transcripts or logs through these public resources.
- Use the current browser session for signed-in reads. Do not copy session cookies into prompts or treat them as durable machine credentials.
- If an external write has an uncertain outcome, inspect or reconcile its recorded status before retrying; keep idempotency keys stable.

## Example user request
“Set up ChatGPT Ads measurement, a voice agent, attribution, CRM leads and calendar booking.”

An agent can guide the browser signup and connection setup, request the needed grants, configure available products, and verify each step. No public account-creation API is advertised here. ChatGPT Ads here is measurement/conversion feedback, not ad creation. A voice agent, CRM write and confirmed booking each have separate authorization and readiness checks. Stop at review/approval boundaries rather than claiming the whole workflow is one unattended action.

## Example journey: From ChatGPT Ads measurement to a confirmed meeting

This is guidance only. Recheck live access and product contracts for the selected tenant/project before every action.

1. Guide signup or sign-in in the browser. The user controls identity, credentials and exact tenant/project selection.
   - Responsible actor: user.
   - Evidence to keep: A current authenticated session and an unambiguous selected tenant and project.
   - Stop if: Identity is incomplete, access is revoked, or the intended tenant/project is ambiguous.
2. Check the selected tenant's requested products in Home. A new signup includes Home/Intelligence, not automatic CRM, Inbox or Voice entitlement. If a product is disabled, use Home's administrator setup page and wait for provisioning and an exact-project grant. If CRM, Inbox or GPT Live needs attention, an administrator can request Retry setup there. Re-read product status after an uncertain response; do not disable a product to force another setup attempt or call an unreviewed write endpoint as an AI tool.
   - Responsible actor: tenant administrator.
   - Evidence to keep: Each requested product has a current tenant entitlement and actor/project grant, and provisioning is no longer pending; product runtime readiness is checked separately.
   - Stop if: Product setup is not configured, requires Datagran support, remains provisioning or lacks the required project grant.
3. Connect the authorized marketing source and configure ChatGPT Ads measurement or conversion feedback where supported; do not promise ChatGPT ad creation.
   - Responsible actor: tenant administrator.
   - Evidence to keep: The exact project has authorized account assignment, a fresh import or observed measurement evidence, and separately verified conversion-delivery status where requested.
   - Stop if: Provider consent, account assignment, fresh import or product entitlement is missing.
4. Review project tracking configuration and source provenance, then observe real touch or conversion records.
   - Responsible actor: authorized operator.
   - Evidence to keep: A project-scoped observed event or conversion record with its source and time, not just a saved tracking setting.
   - Stop if: Only configuration exists or evidence cannot be tied to the selected project.
5. Inspect the selected-project agent list. Before creating a new agent, run Voice creation preflight with current user authority. Create or edit only an authorized draft, obtain review before publishing, and verify the intended website or phone channel separately.
   - Responsible actor: voice administrator.
   - Evidence to keep: Published agent version, current project grant, connected channel and an observed test session in that channel.
   - Stop if: Creation preflight denies a new agent, only a draft or saved number exists, the channel is not enabled, or provider readiness is unknown.
6. Resolve the customer identity in the exact CRM workspace and capture a lead with a stable source-event identity where supported.
   - Responsible actor: authorized operator.
   - Evidence to keep: A scoped CRM person and lead receipt linked to the intended source; Home customer and Funnel IDs are reconciled separately.
   - Stop if: The CRM grant is missing, the person belongs to another workspace, or an uncertain person upsert or lead insert has not been inspected.
7. Prepare a reply or follow-up proposal, check recipient consent and sender/channel readiness, then request the required review before sending or activation.
   - Responsible actor: authorized operator.
   - Evidence to keep: A reviewed draft and, only after approval, the platform's send or automation receipt with its actual status.
   - Stop if: Consent, approval, sender readiness or an uncertain-send reconciliation is missing.
8. Approve the exact Calendar/project/agent grant, check current availability, repeat the date and timezone, and request explicit customer confirmation before booking.
   - Responsible actor: calendar owner and customer.
   - Evidence to keep: A provider-backed availability result followed by the original workflow's recorded status: booked receipt for the confirmed time.
   - Stop if: Only a saved grant or proposed slot exists, customer confirmation is absent, or the booking outcome is unknown; reconcile the original request rather than inserting another.
9. Review project-scoped receipts and operational evidence for each requested action, then report completed, pending and uncertain steps separately.
   - Responsible actor: authorized operator.
   - Evidence to keep: Every requested outcome has its own authorized receipt or observed status; missing evidence remains explicitly unknown.
   - Stop if: Any required write, provider action or cross-service identity link lacks verifiable evidence.

## Example journey: From connected sources to reviewed AI guidance

This is guidance only. Recheck live access and product contracts for the selected tenant/project before every action.

1. Confirm the exact tenant and project, the sources the user wants to use, and any provider consent. The user controls sign-in, credentials and consent.
   - Responsible actor: user.
   - Evidence to keep: A current authenticated session, an unambiguous tenant and project, and a user-approved source list.
   - Stop if: The selected scope is ambiguous, access was revoked, or a requested source lacks consent.
2. Connect only supported sources and assign their allowed capabilities to the selected project. Check saved assignments and provider access separately.
   - Responsible actor: tenant administrator.
   - Evidence to keep: The exact project has saved source assignments and a separate current provider check where the product supports one.
   - Stop if: Only a tenant-level connection exists, its project assignment is missing, or provider access is unknown.
3. Check Intelligence feature grants, optional Memory access, Groovy product access, license, worker connection and tool grants independently. A Home launch does not make Groovy ready.
   - Responsible actor: authorized operator.
   - Evidence to keep: Current project grants and product-owned preflight evidence for the selected Groovy workspace and worker.
   - Stop if: A feature grant, license, worker connection or required tool approval is missing; a recent heartbeat alone is not task execution.
4. Review consented source provenance, Memory access and retention, and Guardrails policy drafts. Ask for review before activation where supported.
   - Responsible actor: tenant administrator.
   - Evidence to keep: A scoped source inventory, saved access and retention settings, and the recorded policy review or active status for each requested change.
   - Stop if: Source consent or provenance is missing, retention is unresolved, or only a saved policy draft exists.
5. Select a Mind, worker and approved skills for one controlled read or proposal task. Inspect the owned task and its safe diagnostics before any retry.
   - Responsible actor: licensed groovy user.
   - Evidence to keep: An owned task receipt and product-owned diagnostics showing a completed result, not only a queued or running state.
   - Stop if: The task awaits approval, remains queued or running, fails, or has an uncertain outcome that has not been inspected.
6. Review source-backed recommendations and observed outcomes. Approve, reject or withdraw each proposed learning change through the authorized product flow.
   - Responsible actor: authorized reviewer.
   - Evidence to keep: A recorded decision tied to source and outcome evidence, followed by an observed result or an explicit pending state.
   - Stop if: The recommendation lacks provenance, consent, reviewer authority or a way to reverse a harmful change.
7. Compare Home project activity with product-owned task and session diagnostics. Keep missing data unknown; do not assume IDs from different services form one trace.
   - Responsible actor: authorized operator.
   - Evidence to keep: Separate authorized receipts or observed statuses for each service, with unresolved gaps reported as unknown.
   - Stop if: A required result is missing, a cross-service identity link is unproven, or raw customer logs would be exposed.

Choose only the journey the user requested. Groovy orchestration and learning changes are not part of a meeting setup request unless the user asks for them.