Use the Agent Factory Python SDK

Install the release-matched Python SDK to run authorized Agent Factory agents and manage supported resources from an application.

The SDK supports Custom Workflows, RAG Agents, Data Analysis Agents, and Deep Research RAG Agents. It also provides clients for file, database, web, and REST API data sources and for LLM and embedding model connections. SDK calls follow the same Agent Factory authorization rules as the application.

For client classes, method parameters, return values, and examples, see the Agent Factory Python SDK API Reference.

Who Uses the SDK

User SDK task
Agent Factory user Run Custom Workflows and pre-built agents that the user can access.
Data-source owner or collaborator List and manage supported data sources within the user’s permissions.
Model administrator or authorized model user List and manage LLM and embedding model connections within the user’s permissions.
Python developer Add agent execution, resource management, authentication, and error handling to an application.
Agent Factory administrator Configure SSO and resource access, and investigate authorized SDK activity.

Before You Begin

Install the SDK

In the Agent Factory kit staging directory, locate the wheel under applied-ai/kit/sdk. Install it in a Python virtual environment:

python -m venv <environment-name>

Activate the environment, then install the wheel for your Agent Factory release:

python -m pip install <staging>/applied-ai/kit/sdk/agentFactory-26.10.0.0.0-py3-none-any.whl

When you upgrade Agent Factory, obtain the new SDK wheel from the upgraded kit and install it with python -m pip install --upgrade <wheel-path>. Agent Factory checks the installed SDK version before login and other supported requests. It accepts the current version and up to two explicitly supported older releases, warns when an accepted version is older, and rejects unsupported versions.

Note: SDK compatibility begins with release 26.10; earlier SDK releases are outside this compatibility window. The SDK does not install or upgrade itself when Agent Factory is upgraded.

The Agent Factory installation or upgrade must apply the SDK database changes. SDK SSO session refresh uses an internal encryption key stored in the Agent Factory wallet. See Upgrade Agent Factory for the application upgrade procedure.

Authenticate and Run an Agent

Create one agentFactory.Configuration and reuse it for authentication and subsequent SDK clients. For username and password authentication:

import agentFactory
from agentFactory import auth, agents

configuration = agentFactory.Configuration(
    host="https://<hostname>:8080/agentFactory/v1",
    username="<username>",
    password="<password>",
)

print("Login status:", auth.login(configuration))
client = agents.AgentBuilder(configuration)
response = client.run(agent_id="<agent-id>", message="Hello")
print(response.message)

To use a configured SSO provider, create the configuration with host and call agentFactory.sso.login(configuration) instead of auth.login(configuration). The SDK opens a browser-assisted sign-in flow and a local loopback callback listener. Run the Python process and browser on the same machine and in the same user session. Reuse the authenticated configuration for later calls. Do not log or persist bearer tokens in plaintext.

To run other agent types, use agents.Knowledge, agents.DataAnalysis, or agents.DeepResearch with the same configuration. Each concrete agent client can list agents visible to the authenticated user. Omit room_id to start a conversation; pass the returned room ID to continue an authorized conversation.

Manage Data Sources and Model Connections

Authenticate with username and password or configured SSO before you create, edit, or remove data sources. Model-connection create, edit, and remove operations require an active SSO bearer session. Agent Factory applies the authenticated user’s existing resource permissions.

Resource SDK clients
File, database, web, and REST API data sources agentFactory.data_sources.FileSource, DatabaseSource, WebSource, and RestApiSource
LLM and embedding model connections agentFactory.model_connections.LLM and Embedding

Create a client with the authenticated configuration, then use its list, create, edit, or remove methods as supported by that resource type. The service checks ownership, sharing, and other applicable permissions for every operation.

File and web data-source clients also provide get_ingestion_status(source_id) to check processing progress and readiness. An administrator can list Agent Factory users with agentFactory.users.Users(configuration).list(). See the SDK API Reference for methods and responses.

Access and Security Limits

The SDK uses existing Agent Factory services and permissions. It does not grant access to agents, rooms, data sources, or models that the authenticated user cannot access in Agent Factory. It does not change Agent Factory browser workflows or screens.

Data sources and model connections continue to use Agent Factory’s existing storage and authorization controls. For refresh-capable SDK SSO sessions, identity-provider refresh tokens are encrypted with a dedicated key held in the Agent Factory wallet; the key is not stored in application tables. SDK activity records do not store request bodies, passwords, cookies, bearer tokens, API keys, or resource secrets.

Diagnose SDK Requests

Agent Factory returns an X-Correlation-ID response header for SDK requests. Use this ID to match a client request to its SDK activity record and server logs. Activity records include the operation, outcome, HTTP status, error code when available, request duration, and associated agent or room IDs when available. They retain safe request metadata such as the method and route, and are kept for 30 days.

When you contact support, provide the correlation ID when available and the error’s code and operation_name. For a service error, also provide its status. Keep passwords, API keys, bearer tokens, and sensitive request contents out of application logs and support reports.

Resolve SDK Errors

The SDK raises agentFactory.exceptions.ServiceError when Agent Factory returns an HTTP error. It raises agentFactory.exceptions.ClientError when the SDK cannot prepare, send, or process a request. Both inherit from AgentFactoryError.

HTTP Service Errors

HTTP status Error code or condition Action
400 or 422 Invalid request or resource identifier Check the request values, agent or room ID, and resource configuration.
401 AUTH_REQUIRED, USER_DISABLED, or REAUTH_REQUIRED Sign in again if the session expired. For a disabled user, contact an administrator. For REAUTH_REQUIRED, repeat SSO sign-in.
403 Resource authorization error Confirm that the authenticated user has access to the agent, room, data source, or model.
426 SDK_VERSION_UNSUPPORTED Install a version listed by the compatibility endpoint. A previously supported version can become unsupported after an upgrade.
500 SDK_SSO_TOKEN_PROTECTION_INVALID or TOKEN_PROTECTION_FAILED Ask an administrator to check the SDK SSO encryption configuration.
503 SDK_COMPATIBILITY_UNAVAILABLE Ask an administrator to verify the deployed release metadata.

Other service failures retain their endpoint-specific status and error code. Use the ServiceError fields status, code, message, operation_name, and correlation_id when investigating the request.

Client-Side Errors

ClientError.code Action
CONFIGURATION_INVALID Check the Agent Factory host and SDK configuration.
SDK_VERSION_UNAVAILABLE Check that the SDK wheel is installed correctly in the active Python environment.
CONNECTION_FAILED or REQUEST_TIMEOUT Check the URL, network access, TLS certificates, proxy settings, and target service availability.
RESPONSE_INVALID Check the Agent Factory deployment and contact support if the response remains invalid.
INVALID_REQUEST Check required parameters and local file paths.
AUTH_REQUIRED Authenticate before calling the operation. If the session expired, sign in again.