Quickstart: Python

Python SDK requires Python 3.11+ and httpx.

#Install

python -m pip install intentlayer

For repository development:

python -m pip install -e sdk

#Configure and gate

import os
import intentlayer

intentlayer.init(
    api_key=os.environ["INTENTLAYER_API_KEY"],
    base_url=os.environ.get("INTENTLAYER_URL", "http://localhost:8000"),
    mode="observe",
)

result = intentlayer.gate(
    "refund order 4821",
    "conversation-42",
    context={"channel": "support"},
)

Use same stable, opaque session_id across turns in one conversation. Do not put email, phone, name, or raw account ID in it.

#Wrap agent function

Wrapped function must accept request and session_id as first two arguments. Decorator calls gate, then always calls host function.

@intentlayer.wrap
def run_agent(request: str, session_id: str) -> str:
    return execute(request)

answer = run_agent("refund order 4821", "conversation-42")

Async functions are supported; wrapper uses gate_async.

#Record outcome

intentlayer.record_outcome(
    "conversation-42",
    event="accept",
    detail=answer,
)

Supported events: rephrase, accept, regenerate, abandon, and correction. Set gate_caught=True only when clarification prevented known bad execution. Telemetry posts in daemon thread.

#Verify arrival

curl "$INTENTLAYER_URL/v1/overview" \
  -H "Authorization: Bearer $INTENTLAYER_API_KEY"

Gate and telemetry network errors are swallowed. Fallback is GateResult(ambiguity_score=0.0, dimensions={}, questions=[], intent_spec=None).