Agent Connections API

Purpose and Scope

Agent Connections V2 is the API family for attaching external authorization tokens to a specific agent. In the official API pages, a connection is the record that links an agent_id to an oauth_token_id, records the provider identity, exposes granted scopes, and carries lifecycle metadata such as creation time and expiration. This page preserves the create, list, and remove operations as a focused reference for developers wiring hosted agent deployments to user-authorized external services.

LangChain’s repository README frames the project as an agent engineering platform for building agents and LLM-powered applications. That framing matters for connections because connections are not local Python tools; they are platform-side authorization resources used by deployed or managed agents when they need access to third-party systems. The README also points readers to LangSmith Deployment for deploying and scaling agents with long-running, stateful workflows, which is the environment where persistent agent-level connection records become operationally relevant. Sources: README.md

Relevant Source Files

• README.md — Establishes LangChain as an agent engineering platform, links to the official documentation site, and places integrations, LangSmith, and deployment in the broader ecosystem used by agent applications.

The only repository file targeted for this page is the top-level README, so this page intentionally treats the Agent Connections endpoint contract as official product API evidence rather than as Python package implementation details. The README is still important because it explains the repository’s public positioning: LangChain helps developers chain interoperable components and third-party integrations while preserving model and integration flexibility. Connections are one way the hosted platform expresses that integration boundary for agents that need authorization to external accounts. Sources: README.md

Core Concepts

An agent connection represents a durable association between one agent and one OAuth token. The token itself is identified by oauth_token_id; the connection response also includes provider_id, an optional provider_account_label, a list of scopes, expires_at, created_by, and created_at. Treat the connection identifier as the resource handle for later removal, while treating the OAuth token identifier as the credential reference supplied when the connection is first created.

This distinction is useful when designing agent administration flows. OAuth token creation or acquisition is a prerequisite handled elsewhere in the auth product surface, while Agent Connections V2 answers a narrower question: which OAuth-backed accounts is this agent currently allowed to use? Listing connections answers that question for an agent. Creating a connection grants that agent access to an existing token. Removing a connection revokes the association between that agent and the connection record without requiring the application to model provider-specific cleanup behavior in the same call.

Connections also differ from local LangChain tools. A local tool is code made available to an agent runtime, usually inside the application process or orchestration graph. A connection is an authorization binding for an external provider account. In a complete agent system, both may be present: a tool defines the callable capability, while a connection determines whether a hosted agent can act through an authorized external account when invoking provider-backed functionality.

Endpoint Reference

The shared response shape for a created or listed connection includes id, agent_id, oauth_token_id, provider_id, provider_account_label, scopes, expires_at, created_by, and created_at. The API documentation marks most fields as required in the response object, while provider_account_label may be null and expires_at may be null. Clients should therefore avoid assuming that every provider account has a display label or that every connection has a known expiration timestamp.

The documented error signal across these endpoints is 422, which corresponds to validation-style failures in the official examples. For client code, this means path parameters and body fields should be validated before a request is sent, especially the required agent_id, connection_id, and oauth_token_id values. A removal request should also be written so that 204 is treated as success even when no JSON payload is returned.

Request Examples

Create a connection after an OAuth token has already been issued or selected for the provider account:

curl --request POST \
  --url https://api.example.com/v2/auth/agents/{agent_id}/connections \
  --header 'Content-Type: application/json' \
  --data '{
    "oauth_token_id": "<string>"
  }'

List all connections currently associated with an agent:

curl --request GET \
  --url https://api.example.com/v2/auth/agents/{agent_id}/connections

Remove a specific connection from an agent when that authorization should no longer be available:

curl --request DELETE \
  --url https://api.example.com/v2/auth/agents/{agent_id}/connections/{connection_id}

Use these examples as transport-level contracts rather than as Python SDK calls. They show the canonical HTTP surface: an agent-scoped collection endpoint for listing and creating connections, and an agent-scoped item endpoint for deleting one connection. If your application exposes an admin UI, the natural workflow is to list existing connections, ask the operator or end user to select or authorize an OAuth token, create the connection, and refresh the list to show the resulting provider account label and scopes.

System-to-Code Mapping

Within this repository’s documentation spine, Agent Connections belongs beside integrations, deployment, and agent runtime topics rather than inside the core model or runnable abstractions. The README says LangChain can be used standalone, but also integrates with LangChain products that support the full lifecycle of LLM applications. That lifecycle includes external provider access, observability, deployment, and long-running workflows. Agent Connections V2 is therefore best understood as a platform API used around an agent, not as a replacement for the local langchain package primitives. Sources: README.md

When implementing against these endpoints, keep application responsibilities separated. The UI or backend service that manages authorizations should store the returned connection id if it needs to later remove the association. The agent runtime should rely on the platform’s connection state instead of embedding raw OAuth token identifiers into prompts or application state. This separation reduces credential exposure, keeps audit metadata such as created_by and created_at available, and lets operators reason about which external accounts each agent can access.

Next Steps

Start by deciding where connection management belongs in your product: an administrator console, an end-user account-linking flow, or a deployment setup step. Then implement the three-resource lifecycle exactly as documented: list existing connections for visibility, create a connection from a known OAuth token, and remove obsolete connections by connection id. After that, connect this API work to the agent’s tool and integration design so authorization state and callable capabilities are reviewed together.

Related pages to read next: tool-integrations for how external capabilities are exposed to agents, mcp for managed tool connectivity patterns, openapi-integration for API-driven tool construction, and api-reference-auth-service-v2-authenticate for deployment and authentication context.