Skip to main content

​
Outcome

Sessions that run as the underwriting agent have the vendor’s API key in the environment and can call the vendor’s REST API. No other agent or person in the org receives that key.

​
Before you start

  • You are an admin of the organization.
  • The vendor issues an API key or token. Middesk is used below; Persona and Alloy follow the same steps with their own field and environment variable names.
  • The underwriting agent exists on the roster and has a default template with a runbook skill attached.

​
Do it

1

Define the provider

In Settings > Context > Tools & MCP click New tool or MCP server, choose Tool, and define a custom provider. Category custom, one static auth method with a secret field api_key, materialized as MIDDESK_API_KEY. Use the vendor’s sandbox key while you build.
2

Connect it to the agent only

Open Add a provider, pick Middesk, paste the key, and choose the agent scope, then select the underwriting agent. An agent connection is used only by sessions that run as that agent and wins over any personal or org-wide connection for the same provider. The CLI creates only org and personal connections; the agent scope is set in the dashboard, or with scope: "agent" and agent_id on POST /api/cloud/knowledge/integrations.
3

Require it from the skill

Add middesk to requires.integrations in the agent’s runbook skill. Agent connections reach the agent’s sessions even without this, but declaring it keeps the requirement visible and lets the same runbook work if you later switch to an org-wide connection.
4

Teach the runbook the endpoints

Put the calls the agent may make in the skill, for example GET /v1/businesses/{id} and GET /v1/businesses/{id}/documents, and state that the agent never creates or updates a business record. That prohibition becomes a deny rule in step 6 of Build once the agent has passed its seeded cases.

​
Verify

Run the agent once from its trigger, or create a session with the agent’s id, then read the environment and call the vendor. A session launched from the same template by a person, without the agent’s identity, must not see MIDDESK_API_KEY at all. That is the agent scope working.

​
Gotchas

  • Wrong scope, wrong runs. An org-wide KYB key reaches every template whose skill requires middesk, including a support agent that has no business reading applications. Keep verification vendors agent-scoped.
  • Sandbox key in production. The vendor’s sandbox key returns synthetic businesses. Swap the connection’s credential before the first real run; the provider definition does not change.
  • Rate limits are yours. The agent calls the vendor API directly. Put the vendor’s rate limit in the runbook so a periodic review does not burn the quota.

3. Give it tools

Custom providers, the three connection scopes, and how a run picks a credential.