Getting Started

Getting Started

This walkthrough uses langchain-algenta end to end. Every other package follows the same shape — the per-framework guides linked at the bottom have the equivalent examples from each package's own README.

Prerequisites

• A running self-hosted Algenta engine, reachable over MCP. There is no Algenta-hosted cloud service to point at instead; see Self-Hosted for how the endpoint resolves.
• A model-provider API key for whichever chat model you use — OPENAI_API_KEY in the example below. This is your model provider's key, not an Algenta credential.
• Python 3.10+.

No engine yet? Skip to Try it locally — it runs the same code against a real local stub server with neither an engine nor a model key.

Install

pip install "langchain-algenta[quickstart]"

The [quickstart] extra adds the full langchain package (needed for langchain.agents.create_agent); langchain-algenta itself only needs the lightweight langchain-core. If you build your agent directly on langgraph or another orchestration layer, pip install langchain-algenta is enough — the tools are plain BaseTools.

Quickstart

import asyncio

from langchain.agents import create_agent
from langchain_algenta import create_algenta_tools

async def main() -> None:
    tools = await create_algenta_tools(base_url="http://localhost:8000/mcp", profile="observe")
    agent = create_agent("openai:gpt-5", tools=tools)
    result = await agent.ainvoke(
        {"messages": [{"role": "user", "content": "What's the expected value of scenario X?"}]}
    )
    print(result["messages"][-1].content)

asyncio.run(main())

profile="observe" is the default and read-only: the agent can call get_contract, query_data, simulate, and recommend — nothing that plans, logs, or executes anything. Opt into more with profile="govern" or profile="execute" (see Tool Contract).

Catching a policy denial

On the execute profile, a call the engine's policy refuses raises a catchable AlgentaExecutionBlocked, synchronously, naming the gate:

from langchain_algenta import AlgentaExecutionBlocked

try:
    result = await agent.ainvoke(
        {"messages": [{"role": "user", "content": "Execute the decision we just logged."}]}
    )
except AlgentaExecutionBlocked as blocked:
    # blocked.gate is one of "idempotency" | "confidence" | "risk_floor"
    print(f"blocked by the {blocked.gate!r} gate: {blocked.denial.message}")

It is deliberately not a ToolException, so LangChain's error-swallowing machinery will not absorb it into a chat message — a policy denial reaches your code, and you decide what the agent is told.

Try it locally (no live engine required)

From a checkout of the repository, the package's own stub MCP server — a real mcp.server.fastmcp.FastMCP server on a real local HTTP socket, the same fixture its 55-test suite runs against — stands in for your engine:

git clone https://github.com/thyn-ai/algenta-integrations
cd algenta-integrations/python
uv sync --all-packages --all-extras

# local_quickstart.py — run from algenta-integrations/python
import asyncio
import sys
from pathlib import Path

sys.path.insert(0, str(Path("langchain-algenta/tests").resolve()))
from stub_server import StubServerFixture  # the same fixture langchain-algenta's own tests use

from langchain_algenta import create_algenta_tools

async def main() -> None:
    async with StubServerFixture() as server:
        print(f"Stub Algenta MCP server listening at {server.base_url}")
        tools = await create_algenta_tools(base_url=server.base_url, profile="observe")
        print("Tools exposed by the 'observe' profile:", [tool.name for tool in tools])
        get_contract = next(tool for tool in tools if tool.name == "get_contract")
        print("get_contract() ->", await get_contract.ainvoke({}))

asyncio.run(main())

uv run --package langchain-algenta python local_quickstart.py

Prints the four observe tools and a real contract payload — no LLM, no API key, no network beyond 127.0.0.1. Every other package's README has an equivalent "Try it locally" section.

Where each framework's guide lives

Framework	Wiki guide	Package README (full detail)
LangChain / LangGraph	LangChain	python/langchain-algenta
LlamaIndex	LlamaIndex	python/llamaindex-algenta
pydantic-ai	PydanticAI	python/pydantic-ai-algenta
Microsoft Agent Framework	MicrosoftAgentFramework	python/maf-algenta
Haystack	Haystack	python/haystack-algenta
LiteLLM (MCP Gateway)	LiteLLM	python/litellm-algenta
Ray Serve / KubeRay	RayServe	python/ray-serve-algenta
vLLM / OpenAI-compatible	VLLM	python/vllm-algenta
Vercel AI SDK	VercelAISDK	typescript/algenta-tools
n8n	N8N	typescript/n8n-nodes-algenta

The package READMEs are the exhaustive reference — denial mappings, dependency rationale, and known upstream incompatibilities, all verified against installed framework versions.