Skip to content
How to use
Automate with an AI Agent
.md

Automate with an AI Agent

Everything in these guides can be driven by an AI agent instead of by code. The MCP server exposes the API v2 surface - reference lookups, audiences, activations, cohorts and POI data - as tools an agent can call, and every tool call behaves exactly like the REST endpoint it wraps: same validation, same envelope, same rate limits.

This is the journey version of MCP > Getting started: what a complete, well-behaved agent run looks like from connection to delivered audience.

1. Connect the agent

Point your client at https://console.intuizi.com/api/v2/mcp (Streamable HTTP). If it supports OAuth, that URL is all it needs: it sends you to an Intuizi consent screen and there is no credential to handle. For an unattended run, mint an MCP token with Create MCP Token and send it as an Authorization: Bearer header instead. Ready-made configuration snippets for both paths are in MCP > Getting started.

A few properties worth knowing before you hand a token to an agent:

  • MCP tokens are long-lived (one year by default) and are not rotated by console logins, so an unattended agent keeps working between sessions.
  • The token carries your account’s access. An agent holding it can do anything you can do through the API, including creating live deliveries.
  • To disconnect an agent permanently, revoke the tokens with Revoke MCP Tokens. Changing your password revokes them too.

2. The loop: lookup, create, poll, activate

Every Intuizi journey an agent can run is the same four-beat loop. The tools per beat, with the endpoint each one wraps, are in the Tools reference.

BeatToolsWhat the agent is doing
Lookuplookup_referenceReading the catalogs to discover real ids and values.
Createcreate_audience, create_cohort, create_lookalike_audienceSubmitting the work; the response returns an id immediately.
Pollget_audience, get_cohort, get_activationWaiting for the lifecycle status to reach 104 Completed.
Activatelookup_reference, then create_activationResolving the destination, then delivering.

Three ordering rules make the difference between a run that works and a run that argues with 422s:

  1. Never invent an id. Ids come from lookup_reference, from a create response, or from a list tool - never from the model’s memory. The catalogs are specific to your account, so a plausible-looking id is usually a wrong one.
  2. Some lookups need a parent value first. Provider and geo catalogs cascade from a chosen dataset type or country, and the pricing and datastream catalogs need the partner_id of the connection you picked. The tool descriptions state each requirement; Working with Reference Data is the long form.
  3. 104 Completed is the only terminal success state, and 105 DataStreaming happens before it. An agent that stops at 105 reports success too early.

What the agent should do at each beat

  • Lookup. Read the dataset types the account can use, then the catalogs for the dataset being targeted. Have the agent show you the shortlisted values before it builds anything - see Working with Reference Data.
  • Create. Build the audience from those values only, and pass an idempotency_key (below). See Create an Audience.
  • Poll. Call get_audience until data[0].status.id is 104, backing off between calls. Then read results_count and is_activation_allowed (and eligibility.reasons when it is false - e.g. an Affinity audience needs unique EIDs above 2x unique SCIDs; the observed counts are in the reason) - an audience under 500 devices cannot be activated, and knowing that before the activation attempt saves a wasted write.
  • Activate. Read endpoint-connections, then the pricing models and datastreams for that connection’s partner.id, and send create_activation. The per-partner details - index-matched inputs, enabling streams, service-account keys - are in Deliver to a Partner Endpoint. Then poll get_activation to 104.

The server also ships a guided prompt, build_and_activate_audience, that walks an agent through exactly this order. Invoking it is the fastest way to get a correct first run.

3. Make every create retryable with idempotency_key

An agent retries. A dropped tool call, a 429, a context reset mid-run - any of them can leave the agent unsure whether a create actually landed. The create tools take an idempotency_key argument that maps to the Idempotency-Key header, with identical semantics:

  • Generate one key per logical create (a UUID is typical) and pass it on the first attempt.
  • Reuse that same key on every retry of that same create. If the original succeeded, the retry replays the original response instead of creating a second resource; if it never ran, the retry executes cleanly.
  • Do not reuse a key for a genuinely new create. The same key with a different body is rejected with 409.

The tools that accept it are the five creates: create_audience, create_lookalike_audience, create_cohort, create_activation and create_project. Full semantics are on Idempotency.

create_activation is the one to be strict about. An activation is a live, billable, non-reversible delivery to an external destination, so a duplicated create is a duplicated delivery. Always pass an idempotency_key, and prefer having the agent confirm the audience, the connection and the pricing model with you before it calls the tool.

4. Respect the rate limits

Tool calls consume the same per-token buckets as direct API calls - an MCP token is not a separate allowance:

BucketLimitWhat counts
Read120 requests/minlookup_reference, every list_* and get_* tool, and every poll
Write30 requests/minEvery write tool: the creates, the deletes, and cancel_lookalike
MCP endpoint120 requests/minEvery request to the MCP endpoint itself

Polling is read traffic, so a tight poll loop is the easiest way for an agent to exhaust 120 reads/min on its own. Have it poll on a few seconds’ interval and back off as the wait grows (for example 5s, then 10s, then 30s), with an overall timeout so a stuck job does not poll forever.

On a 429 the tool error text includes the Retry-After seconds. The correct behavior is to wait that long and then retry - not to loop immediately, and not to re-issue the create without its idempotency_key. Tool errors carry the API’s error envelope verbatim, so an agent can read code and message and act on them. Polling and Rate Limits has the full detail.

5. Ask for the whole journey

Once connected, the work is expressed as a request rather than as code. For example:

Using Intuizi: find the POI brands matching "Acme Coffee", build an audience of
devices seen at them in the United States last month, poll it until it is
Completed, and tell me the results count. Do not activate anything yet - show me
the audience first.

Then, after you have reviewed it:

Activate audience 88 to my "Acme Production" endpoint connection using the CPM
pricing model, enable the Match File datastream, and poll until the delivery is
Completed.

Both halves of that run are ordinary journeys from these guides - the agent is just holding the pen. Keeping the irreversible step in a second, explicitly confirmed instruction is the pattern we recommend: create_activation and the delete tools are the ones whose consequences you cannot take back by asking again.

Reference

Polling & Rate Limits