Typescript sdk

Remote Agent Configuration

Copy page

Learn how to configure and use external agents for A2A communication

External agents are agents external to a graph that can communicate using the A2A (Agent-to-Agent) protocol. External agents enable you to delegate tasks between graphs within the agent framework or to third-party services.

Creating an External Agent

Every external agent needs a unique identifier, name, description, base URL for A2A communication, and 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",
});

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, technicalExternalAgent],
});

External Agent Options

The framework supports comprehensive external agent configuration including authentication and custom headers:

const externalAgent = 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
Agent RelationshipsMCP Servers