Importing LangGraph agents

Why use LangGraph agents

LangGraph is a programming framework for building agents with Large Language Models (LLMs) that extends LangChain with the ability to create cyclical graphs. This enables agents to have complex reasoning patterns beyond simple ReAct loops, custom state management for custom workflows, multi-step orchestration with conditional logic, and full control over agent behavior and decision-making.

Importing LangGraph agents into watsonx Orchestrate solves the following challenges:

Deploying existing LangGraph agents: If you have a LangGraph agent that works in development but need production infrastructure such as hosting, security, authentication, monitoring, and policy enforcement without rewriting your agent, you can import it into watsonx Orchestrate and instantly gain access to additional capabilities with minimal code changes.

Building specialized agents: When standard ReAct agents have limitations and you need custom reasoning patterns, complex state management, multi-stage workflows, or specialized logic beyond tool selection, you can write custom LangGraph agents with full control over logic and reasoning, then run them in watsonx Orchestrate like other native agents.

How imported LangGraph agents work

LangGraph agents that are imported into watsonx Orchestrate run natively within the platform runtime infrastructure. Unlike external agents that maintain their own hosting, imported LangGraph agents are fully integrated into the watsonx Orchestrate platform. This means:

The agent code runs within the watsonx Orchestrate environment with required isolation.
watsonx Orchestrate manages the agent lifecycle, scaling, and resource allocation.
The agent benefits from watsonx Orchestrate security, monitoring, and operational capabilities.
Communication happens through the A2A (Agent-to-Agent) protocol for collaboration with other agents.
Imported LangGraph agents can be used as top-level agents or collaborators for other agents.
They can be seen and configured into the platform, and can be deployed to Live environments.

Before you begin

Before importing a LangGraph agent, ensure you have:

LangGraph package

Provide a properly structured LangGraph agent package (ZIP file) containing:

agent.yaml configuration file
At least one factory function (.py file)
requirements.txt file

For information about building LangGraph agent packages, see Creating a LangGraph package for import.

Connections

If your agent calls external LLMs or tools that require authentication, create all required connections that your agent needs so you can select them during the import process. For more information, see Creating connections for LangGraph agents.

Important: You must create all required connections before importing the agent. The import process does not validate required connections, so ensure all necessary connections exist and are properly configured before proceeding.

Import limit

Verify whether the tenant do not reached the limit of 3 LangGraph agents.

Validation requirements

Before importing, your agent package must pass these validations:

File structure validations

ZIP file is not corrupted
Contains agent.yaml file
Contains at least one .py file
Contains requirements.txt file

Configuration validations

The agent.yaml file is valid YAML.
The spec_version field exists and equals v1.
The kind field exists and equals agent.
The name field exists, is not empty, and does not exceed 40 characters.
The description field exists and is not empty.
The deployment.code_bundle.entrypoint field exists and follows module:function format.

Limitations and restrictions

Be aware of these limitations when working with imported LangGraph agents:

Tenant limits

Each tenant is subject to a maximum limit of three LangGraph agents. This limit counts all LangGraph agents, including those that you import and those that you copy to workspaces. If this limit is reached, any attempt to import additional LangGraph agents results in a “limit exceeded” error. You must account for both imported and copied agents when managing LangGraph usage within a tenant.

Connection requirements

You must create all connections before importing the agent, and only team credential-configured connections are supported.

Note: The system does not validate whether selected connections match your agent's requirements.

State persistence

Only messages in the agent graph are preserved between conversation turns. Complex custom state objects are not persisted between turns.

For more information about how to enable state persistence for LangGraph agent, see Enabling state persistence for LangGraph agents.

Agent collaboration

Agents native from watsonx Orchestrate can use LangGraph agents as collaborators, but LangGraph agents cannot use native agents as collaborators.

Tools and integrations

Tools included in your agent package are not exposed as watsonx Orchestrate tools, and are supported in read-only mode only. Also:

You cannot use your LangGraph agent's tools in other agents.
watsonx Orchestrate tools such as agentic workflows, Python tools, MCP tools, and OpenAPI tools are not supported for LangGraph agents.

Other limitations

Currently, only Python-based LangGraph agents are supported.

Important: For related limitations and known behaviors, check the Known issues section.

Procedure

Follow the steps to import the LangGraph agent to watsonx Orchestrate.

Step 1: Import the agent package

Go to the agents and tools page in watsonx Orchestrate.
Click Create agent + > Import LangGraph agent.
Upload the LangGraph agent package.
- ZIP file is not corrupted
- Contains agent.yaml file
- Contains at least one .py file
- Contains requirements.txt file
- agent.yaml has valid YAML syntax
- Required configuration fields are present and valid
If validation fails, an error message displays indicating what you need to adjust. Fix the issues in your agent package and try uploading again.
If validation succeeds, click Next to proceed to connection selection.

Step 2: Select connections

The connections screen displays all available team connections in your instance.
Select all connections that your agent requires to function properly:
- For LLM-based agents, select the connection for your language model provider.
- For agents using external APIs, select connections for each API your agent calls.
- If your agent does not require any connections, you can skip this step.
Click Next to complete the import.

Note: All connections are listed without filtering. You are responsible for selecting the correct connections that match what your agent factory function expects. The system does not validate whether the selected connections are actually required by your agent.

Important:

When you use a LangGraph agent, you cannot edit certain configuration fields through the standard interface.

Agent style
Voice configuration
Knowledge
Tools
Collaborator agents
Guidelines
Chat with documents

To change any of these settings, update the LangGraph agent code directly, and re-import the package.

What to do next

After importing your LangGraph agent, you can enhance it with additional watsonx Orchestrate capabilities by using the ADK:

AI Gateway integration: Use watsonx Orchestrate LLMs through the standard AI Gateway instead of managing your own LLM connections.

Memory integration: Integrate with watsonx Orchestrate memory services to pull relevant memories for context, push new memories, or maintain conversation continuity across sessions.

Additional instructions: Leverage instructions configured by the agent builder to customize agent behavior without code changes.

Context variables: Access watsonx Orchestrate context variables.

For more information, see the IBM watsonx Orchestrate Agent Development Kit documentation.