Copy page

How-to

External data

An agent that can read your CRM is more useful than one that can only discuss it. External data is the bridge: connect a service once, then let named agents call it mid-conversation.

Gated on the module-external-data entitlement.

Connect a service

GET /integrations/providers lists what can be connected and what each one requires:

Code
hubspot · salesforce · mailchimp · constant-contact · webflow
wordpress · canva · alphavantage · …

It is a static catalog, and deliberately a narrowed view of one: the credential recipe internals are not part of the response. Read it rather than hard-coding the list, because it includes industry-specific providers beyond those above, and providers are added over time.

Code
curl -X POST https://api.genuineai.app/api/v1/integrations \
  -H "X-Api-Key: gai_…" -H "X-Tenant-Id: <workspace-id>" \
  -H "Content-Type: application/json" \
  -d '{
    "conn_name": "Marketing HubSpot",
    "conn_provider": "hubspot",
    "fields": { "…": "…" },
    "allow_write": false
  }'

fields carries whatever that provider's recipe requires. Creating a connection needs integration:create, because connecting a company's CRM is an administrative act rather than something an integration does for itself.

Read-only by default

allow_write is the single most consequential field on a connection:

allow_write	An agent may
false (default)	Call read operations only. Write attempts are refused at execution.
true	Call operations that create, update or delete in the connected system.

Leave it false unless an agent genuinely needs to change the other system. It is enforced when the tool runs rather than only when it is described to the model, so a model that attempts a write anyway is still stopped.

PATCH /integrations/{id} changes it later, and DELETE /integrations/{id} disconnects.

What a connection can do

Code
GET /integrations/{id}/operations?query=contact

Searches the operations this connection exposes, which are the actions an agent can be given through it. query is required, because a connected CRM exposes hundreds of operations and the goal is to find the few that matter rather than enumerate them all.

Call this directly while designing an agent. What you find here is exactly what the agent will be able to reach, so it answers "can this agent do what I need" before you wire it up and test by conversation.

Give an agent access

Two fields on the agent:

Code
{
  "agent_tools": ["external_data"],
  "agent_conns": ["3f2a9c1e-…"]
}

external_data is the tool itself. agent_conns narrows which connections this agent may use.

The narrowing happens when the tool is bound, so the agent's tool description mentions only connections it is allowed to use. It cannot attempt a connection it was not given and be refused, because it does not know that connection exists.

Read/write status travels into that description too. Each connection is presented to the model as read-only or read/write, so it plans accordingly rather than proposing writes it cannot make.

When there are no connections

If a workspace has none, the tool instructs the agent to say so and to explain that an administrator must connect a service first. An agent with external_data and nothing connected explains the situation rather than failing or inventing data.

The same applies to failures: if connections cannot be listed, the tool binds with an empty set rather than ending the conversation.

Design considerations

The combination worth building toward is this page plus autonomous AI: a routine that fires on a schedule, whose copilot agent reads from a connected system, does the work, and submits it for review. Nobody has to start it or remember it.

Two limits shape the design. First, there is no webhook in from these services: the platform reads when an agent asks, so the model is pull rather than push, and a scheduled routine is how you approximate reacting to change. Second, connections are workspace-level, so an agent acts as the connection rather than as the person talking to it, and the connected system's audit log shows the integration rather than the end user.

Next steps

• Agents and conversations holds the tool catalog this belongs to.
• Autonomous AI covers scheduled work that acts on other systems.
• Roles and permissions explains the integration:* permissions.