Custom Connectors - From Your APIs and Databases to Agent Actions

This is part 2 of a short series on connectors. If you have not read part 1, start here: Connectors - From Answers to Actions.

Out-of-the-box connectors cover the common systems (helpdesk, commerce, messaging). But the workflows that actually close tickets often end in the long tail: internal admin APIs, operational databases, data warehouses, and homegrown tools.

Custom connectors are how you bring that long tail into the agent's action surface, without handing it a wide-open API key or an unsafe SQL console.

---

TL;DR

• Think in action contracts: define a small set of named actions with inputs, outputs, and a permission level (read, write, sensitive write).
• Prefer narrow actions: expose “update shipping address” over “PATCH order object”.
• Use the right substrate: HTTP for system APIs, database connectors for verified source-of-truth reads.
• Test before you trust: run actions with sample inputs, validate outputs, and make failures obvious.
• Design for change: version actions, keep outputs stable, and treat dependencies as unreliable.

---

Highlights

• Close the last mile - Connect the internal system where the work actually happens.
• Safer automation - Explicit permission levels and scoped credentials instead of a blanket token.
• Fewer escalations - Resolve common requests end-to-end, and escalate only when it is truly needed.
• More auditability - Every action has a name, an input shape, and an output you can review.

---

The mental model: an action is a contract

When you build a custom connector, you are not just wiring up an integration. You are defining the only “verbs” an agent is allowed to use.

A good action contract answers:

• What is the outcome? (one clear side effect)
• What is the access level? (read vs write vs sensitive write)
• What are the inputs? (typed fields, required vs optional)
• What is the output? (structured response the agent can reason over)
• How does it fail? (errors are explicit, not silent)

This is the difference between “an agent that can call our API” and “an agent that can safely complete a workflow.”

---

A real workflow: “Can you update my shipping address?”

Address changes look simple. In practice, they are full of edge cases: orders that already shipped, fraud controls, split shipments, or an address that fails validation.

Before

• The bot explains the policy and asks the customer to wait.
• A human agent looks up the order, checks shipment status, updates the address, and replies.
• If anything is ambiguous, the customer gets a second follow-up and the ticket re-opens.

After (with a custom connector)

• The agent reads the order (read action) to confirm status and shipping details.
• It checks eligibility (read action) to see whether an address change is still allowed.
• If allowed, it submits the change (write or sensitive write action).
• If not allowed, it escalates with the exact reason and the relevant order context so a human can finish in one step.

The key is that the write action is scoped: it updates only the address fields you permit, and returns a structured “what changed” response that is easy to audit.

---

How to scope actions safely

Custom connectors are most valuable when they are boring: small, predictable, and hard to misuse.

1) Make actions narrow and composable

Avoid “do everything” endpoints. Prefer a small library of specific actions:

• get_order_by_id (read)
• check_address_change_eligibility (read)
• update_shipping_address (write or sensitive write)

This helps the agent choose the right tool, and helps humans understand what happened when reviewing traces.

2) Treat writes as a separate tier

Reads are about correctness. Writes are about risk.

Start with read-only actions first. When you add writes:

• Require the minimum inputs needed to make the change.
• Return a clear, structured output (updated fields, new status, and a human-readable summary).
• Design the action to be idempotent when possible (retries should not double-apply side effects).

3) Use least-privilege credentials

Security is mostly about what the connector is allowed to do when something goes wrong.

• For APIs, use a token scoped to the specific endpoints the action needs.
• For databases, use a read-only user or a dedicated role restricted to a schema, a view, or a small set of tables.

4) Make failure modes part of the contract

External systems will fail. Your connector should fail loudly and predictably.

• Timeouts should produce clear errors.
• Validation failures should return a specific reason (not a vague “bad request”).
• Downstream outages should result in safe fallback behavior (answer from knowledge when possible, or escalate with context).

---

HTTP APIs: turn endpoints into actions

HTTP is the most common substrate for internal systems: admin services, billing tools, fulfillment systems, and niche vendors.

For each HTTP action, define:

• Base URL and auth via secrets (so tokens are not hard-coded)
• Method + path for the operation
• Typed inputs that map cleanly into headers, query params, or request body
• Typed outputs so the agent does not have to parse freeform JSON

The goal is to keep the interface stable even if the underlying service evolves.

---

Databases: use source-of-truth reads

Some workflows require looking at the raw source of truth: the operational database or warehouse where facts are recorded.

Database connectors can be powerful for:

• Joining across systems (orders + shipments + returns)
• Verifying eligibility (subscription status, previous refunds, fraud flags)
• Fetching the one field your API does not expose cleanly

To keep database actions safe over time:

• Prefer views that encode business meaning, not ad-hoc queries.
• Enforce limits (result size, timeouts) and avoid unbounded scans.
• Keep credentials read-only unless you have a strong reason for writes.

If you ever allow database writes, treat them as sensitive writes and keep the surface area extremely small.

---

Reliability over time: permissions, approvals, auditability

“Working once” is easy. “Working every week” is what matters.

Custom connectors stay reliable when you plan for drift:

• Permissions: keep action access levels explicit, and expand only as trust grows.
• Approvals: gate sensitive actions behind confirmation or escalation until you have strong confidence.
• Auditability: name actions clearly and keep inputs and outputs structured so traces are easy to review.
• Safe failures: assume dependencies break and make the fallback path obvious to the customer and the team.

This is how teams move from experiments to automation they can trust.

---

Getting started / rollout

1. Pick one workflow where the last mile is an internal API or database lookup.
2. Define 2-3 read actions and validate you get the exact context the agent needs.
3. Add one write action with the narrowest possible side effect and an explicit permission level.
4. Test with real examples, then roll out gradually and review traces.
5. Iterate: expand coverage only when you trust the failure behavior.

---

FAQ

Do custom connectors require engineering?
Often, yes. The highest leverage approach is a partnership: support ops defines the workflow and action contracts, and engineering exposes or hardens the underlying API or database view.

Should we use an API or a database connector?
Prefer an API when it exists and is stable. Use database reads when the database is the source of truth or when APIs do not expose what you need.

What happens if a dependency is down?
The agent should fail safely: explain what it could not do, avoid guessing, and escalate with the context a human needs to finish quickly.

---

Get in touch

If you want to map your internal systems into safe, permissioned actions for your agent, we can help you scope the right first workflow and rollout plan.

→ Get a demo