Typescript sdk

Add External Agents to your Graph

Copy page

Learn how to configure and use external agents using the A2A protocol

External agents let you integrate agents built outside of Inkeep—using other frameworks or platforms—into your Graph. They communicate over the A2A (Agent‑to‑Agent) protocol so your Inkeep agents can delegate tasks to them as if they were native.

Note
Note

Any agent that exposes an A2A‑compatible HTTP endpoint can be integrated by providing its baseUrl plus headers/auth (static or dynamic).

Learn more about A2A:

Examples of platforms exposing agents via A2A (non‑exhaustive):

Creating an External Agent

Every external agent needs a unique identifier, name, description, base URL for A2A communication, and optional authentication configuration:

import { externalAgent } from "@inkeep/agents-manage-api/builders";

const technicalSupportAgent = externalAgent({
  id: "technical-support-agent",
  name: "Technical Support Team",
  description: "External technical support specialists for complex issues",
  baseUrl: "https://api.example.com/agents/technical-support", // A2A endpoint
});

External Agent Relationships

Agents can be configured to delegate tasks to external agents.

import { agent } from "@inkeep/agents-manage-api/builders";

// Define the customer support agent with delegation capabilities
const supportAgent = agent({
  id: "support-agent",
  name: "Customer Support Agent",
  description: "Handles customer inquiries and escalates technical issues",
  prompt: `You are a customer support agent that handles general customer inquiries.`,
  canDelegateTo: () => [technicalSupportAgent],
});

// Create the customer support graph with external agent capabilities
export const supportGraph = agentGraph({
  id: "customer-support-graph",
  name: "Customer Support System",
  description:
    "Handles customer inquiries and escalates to technical teams when needed",
  defaultAgent: supportAgent,
  agents: () => [supportAgent, technicalSupportAgent],
});

External Agent Options

Configure authentication and custom headers as needed (static values or dynamic context variables).

const supportExternal = externalAgent({
  // Required
  name: "External Support Agent", // Human-readable agent name
  description: "External AI agent for specialized support", // Agent's purpose
  baseUrl: "https://api.example.com/agents/support", // A2A endpoint URL

  // Optional - Static or dynamic headers
  headers: {
    Authorization: "{{requestContext.Authorization}}",
  },

  // Optional - Credential Reference
  credentialReference: myCredentialReference,
});
ParameterTypeRequiredDescription
idstringYesStable agent identifier used for consistency and persistence
namestringYesHuman-readable name for the external agent
descriptionstringYesBrief description of the agent's purpose and capabilities
baseUrlstringYesThe A2A endpoint URL where the external agent can be reached
headersobjectNoHTTP headers to include with every request to the external agent. See Context Fetchers for details about dynamic variables.
credentialReferenceCredentialReferenceNoReference to dynamic credentials for authentication. See Credentials for details
Using Langfuse for LLM ObservabilityGraphs