Agent Factory Python SDK API Reference

Find Python client classes, method parameters, return values, and examples for the Agent Factory SDK in release 26.10.

Install the release-matched wheel and review authentication requirements in Use the Agent Factory Python SDK. Create one agentFactory.Configuration and pass it to authentication and resource clients. Operations use the authenticated user’s existing Agent Factory permissions.

SDK Conventions

These release and listing rules apply across the SDK client classes.

SDK Release Compatibility

The SDK wheel is packaged with its Agent Factory release. Before the first SDK request to a host, the client sends its installed wheel version for compatibility checking. Agent Factory accepts its current SDK version and up to two explicitly supported older versions. An unsupported version receives HTTP 426 SDK_VERSION_UNSUPPORTED. Upgrade the SDK wheel when you upgrade Agent Factory; see Install the SDK.

List Methods and Results

All concrete agent, data-source, and model clients provide list(offset=0, limit=50). offset is the zero-based starting position; limit is the maximum number of entries requested. Lists contain only resources visible to the authenticated user.

For a list across resource types, use agents.Agent(configuration), data_sources.DataSource(configuration), or model_connections.Model(configuration, timeout=120). These generic clients expose list; use a concrete client for type-specific operations.

Return field	Type	Description
`items`	array	Resources in this page.
`count`	integer	Number of returned items.
`offset`	integer	Starting position.
`limit`	integer	Maximum entries requested.
`hasMore`	boolean	Whether another page is available.
`nextOffset`	integer or `null`	Starting position for the next page.

The following example assumes an authenticated configuration, as described in Configuration and Authentication.

from agentFactory import agents

client = agents.AgentBuilder(configuration)
page = client.list(limit=20)
for item in page["items"]:
    print(item["name"], item["id"])

if page["hasMore"]:
    next_page = client.list(offset=page["nextOffset"], limit=20)

The SDK raises ServiceError for Agent Factory HTTP failures and ClientError for local configuration, request, network, or response failures. See Resolve SDK Errors.

Configuration and Authentication

Configuration

agentFactory.Configuration(**kwargs) stores the Agent Factory host and authentication state. Reuse the same instance for each SDK client.

Parameter	Type	Required	Description
`host`	string	Yes	Agent Factory base URL, such as `https://<hostname>:8080/agentFactory/v1`.
`username`	string	Username and password login	Agent Factory user name.
`password`	string	Username and password login	Agent Factory password.

Property	Description
`verify_ssl`	Controls TLS certificate verification. Leave verification enabled in production.
`proxies`	Optional HTTP and HTTPS proxy mapping.
`no_proxy`	Optional host patterns that bypass the proxy.

import agentFactory

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

Username and Password Login

agentFactory.auth.login(configuration) authenticates with configuration.username and configuration.password. The SDK stores the cookie session in the supplied configuration.

Parameter	Type	Required	Description
`configuration`	`agentFactory.Configuration`	Yes	Configuration containing `host`, `username`, and `password`.

Returns: An integer HTTP status. A successful login normally returns 200.

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)

Browser-Assisted SSO Login

agentFactory.sso.login(configuration, open_browser=True, timeout_seconds=300, show_status=True) starts SSO sign-in, opens a local callback listener, and stores the bearer session in the supplied configuration. The Python process and browser must run on the same machine and in the same user session.

Parameter	Type	Required	Description
`configuration`	`agentFactory.Configuration`	Yes	Configuration containing the Agent Factory host.
`open_browser`	boolean	No	Opens the sign-in page automatically. Default: `True`.
`timeout_seconds`	integer	No	Maximum time to wait for the callback. Default: `300`.
`show_status`	boolean	No	Prints non-sensitive sign-in progress. Default: `True`.

Returns: A dictionary with accessToken, tokenType, expiresIn, expiresAt, and userId. The SDK stores accessToken automatically; do not log or persist it in plaintext.

import agentFactory
from agentFactory import agents, sso

configuration = agentFactory.Configuration(
    host="https://<hostname>:8080/agentFactory/v1"
)
session = sso.login(configuration)
print("Logged in as:", session["userId"])

client = agents.Knowledge(configuration)
response = client.run(
    agent_id="<rag-agent-id>",
    message="What can you help me with?",
)
print(response.message)

SSO Session Methods

When you authenticate with SSO, the SDK uses the bearer session in configuration for data-source and model-management operations. Use these methods to refresh or revoke the active session.

Method	Parameters	Return value
`sso.refresh_session(configuration, token=None)`	`configuration` is required; `token` optionally supplies a bearer token.	Dictionary with `accessToken`, `tokenType`, `expiresIn`, `expiresAt`, and `userId`. The SDK updates the token in `configuration`.
`sso.revoke_session(configuration, token=None)`	`configuration` is required; `token` optionally supplies a bearer token.	Dictionary with boolean `revoked`.

When token is omitted, each method uses the bearer token stored in configuration. A revoked, expired, disabled, or otherwise ineligible session can require a new sso.login(configuration) call.

from agentFactory import sso

refreshed = sso.refresh_session(configuration)
print("Session expires at:", refreshed["expiresAt"])

result = sso.revoke_session(configuration)
print("Session revoked:", result["revoked"])

Advanced SSO Methods

Applications that control the sign-in sequence can use these methods. Most applications should use sso.login.

Method	Parameters	Return value
`sso.start(configuration, redirect_uri, code_verifier=None)`	Required `configuration` and local callback `redirect_uri`; optional PKCE `code_verifier`.	Dictionary with `authorizationUrl`, `statusToken`, `expiresIn`, and `codeVerifier`. Preserve the verifier until completion.
`sso.get_status(configuration, status_token)`	Required `configuration` and `status_token` returned by `start`.	Dictionary with `phase`, `updatedAt`, `expiresAt`, `terminal`, and safe `errorCode` when present.
`sso.complete(configuration, completion_code)`	Required `configuration` and one-time `completion_code` received by the callback.	Same session fields as `sso.login`; stores the bearer token in `configuration`.

User Listing

agentFactory.users.Users(configuration) lists Agent Factory users for an authenticated administrator. The client accepts a Configuration with a session established by auth.login(configuration) or sso.login(configuration).

list() takes no parameters and does not use the shared resource pagination structure. It returns a dictionary with items, count, and rolesCount. Each user record includes userId, email, role, status, userTypeId, lastLogin, and joined. rolesCount groups counts by lowercase role name and includes totalUsers.

import agentFactory
from agentFactory import auth, users

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

result = users.Users(configuration).list()
for user in result["items"]:
    print(user["userId"], user["role"], user["status"])
print(result["rolesCount"])

Agent Clients

Each client takes configuration. Use list(offset=0, limit=50) to list visible agents of that type. Published Custom Workflows appear in SDK listings.

Agent list items include id, name, description, icon, agentType, resourceType, published, isOwner, actions, updatedAt, and createdAt. Optional values can be null.

Client class	Agent type	`run` return type
`agents.AgentBuilder(configuration)`	Agent Builder and Custom Workflow	`AgentResponse`
`agents.Knowledge(configuration)`	RAG Agent	`KnowledgeAgentResponse`
`agents.DataAnalysis(configuration)`	Data Analysis Agent	`DataAnalysisAgentResponse`
`agents.DeepResearch(configuration)`	Deep Research RAG Agent	`DeepResearchAgentResponse`

The Agent Builder, RAG Agent, and Data Analysis Agent clients share the run(agent_id, message, room_id=None) parameters. Omit room_id to start a conversation; use the returned room ID to continue it.

Parameter	Type	Required	Description
`agent_id`	string	Yes	Agent ID from Integration options or an authorized list result.
`message`	string	Yes	User message or analysis request.
`room_id`	string	No	Existing conversation room ID.

Agent Builder

agents.AgentBuilder(configuration) provides list(offset=0, limit=50) for visible Agent Builder agents and published Custom Workflows. run(agent_id, message, room_id=None) returns an AgentResponse with response text in message and the conversation ID in room_id.

import agentFactory
from agentFactory import agents, sso

configuration = agentFactory.Configuration(
    host="https://<hostname>:8080/agentFactory/v1"
)
sso.login(configuration)

client = agents.AgentBuilder(configuration)
response = client.run(
    agent_id="<agent-id>",
    message="What can you help me with?",
)
print(response.message)

follow_up = client.run(
    agent_id="<agent-id>",
    message="Please provide more detail.",
    room_id=response.room_id,
)
print(follow_up.message)

RAG Agent

agents.Knowledge(configuration) provides list(offset=0, limit=50) for visible RAG Agents. run(agent_id, message, room_id=None) returns a KnowledgeAgentResponse with message, room_id, and optional Disclaimer, sources, and suggestions. Each source includes title and url.

from agentFactory import agents

knowledge = agents.Knowledge(configuration)
knowledge_response = knowledge.run(
    agent_id="<rag-agent-id>",
    message="What does the travel policy say about hotel expenses?",
)
print(knowledge_response.message)

Data Analysis Agent

agents.DataAnalysis(configuration) provides list(offset=0, limit=50) for visible Data Analysis Agents. run(agent_id, message, room_id=None) returns a DataAnalysisAgentResponse with room_id and message. The message field can contain structured analysis data instead of plain text.

from agentFactory import agents

analysis = agents.DataAnalysis(configuration)
analysis_response = analysis.run(
    agent_id="<data-analysis-agent-id>",
    message="Summarize last quarter's sales trend.",
)
print(analysis_response.message)

Deep Research RAG Agent

agents.DeepResearch(configuration).run(agent_id, message, room_id=None, *, model_id=None, answer_mode=None) runs a research request.

Parameter	Type	Required	Description
`agent_id`	string	Yes	Deep Research RAG Agent ID.
`message`	string	Yes	Research question.
`room_id`	string	No	Existing conversation room ID.
`model_id`	string	No	Authorized LLM connection name; omit for the configured default.
`answer_mode`	string	No	`quick` or `smart`; omit for the configured mode.

Returns: DeepResearchAgentResponse with message, room_id, optional Disclaimer, sources, and suggestions. Each source has a title.

from agentFactory import agents

client = agents.DeepResearch(configuration)
response = client.run(
    agent_id="<deep-research-agent-id>",
    message="Compare the benefits and risks of retrieval-augmented generation.",
    answer_mode="smart",
)
print(response.message)

Data Source Clients

Authenticate with auth.login(configuration) or sso.login(configuration) before using data-source create, edit, remove, or ingestion-status methods. The authenticated user must have the required permissions for the data source.

The examples below reuse the authenticated configuration from the authentication examples.

Client class	Resource	Additional method
`data_sources.FileSource(configuration)`	File data source	`get_ingestion_status(source_id)`
`data_sources.DatabaseSource(configuration)`	Database data source	None
`data_sources.WebSource(configuration)`	Web data source	`get_ingestion_status(source_id)`
`data_sources.RestApiSource(configuration)`	REST API data source	None

Each client provides list(offset=0, limit=50). List items contain id, name, description, resourceType, and status. Create, edit, and remove methods return a dictionary with boolean success and sourceId when the service returns an ID.

Data Source Ingestion Status

data_sources.FileSource and data_sources.WebSource provide get_ingestion_status(source_id). Pass the data-source sourceId returned by creation or the id returned by listing. This method accepts an authenticated cookie or SSO bearer session, and the user must have permission to use the source.

Return field	Type	Description
`sourceId`	string	Data-source identifier.
`sourceType`	string	`file` or `web`.
`status`	string	`PENDING`, `RUNNING`, `FAILED`, or `COMPLETED`.
`ready`	boolean	`True` only when status is `COMPLETED`.
`currentStage`	string or `null`	Current stage, when available: `CRAWLING`, `STORING_CONTENT`, `CHUNKING`, `EMBEDDING`, or `INDEXING`.
`lastRefreshAt`	string or `null`	Recorded last-refresh time, when available.
`errorMessage`	string or `null`	Recorded ingestion error, when available.

PENDING is also returned when no ingestion state has been recorded. A call reports the current state; it does not start ingestion or wait for completion. Applications can repeat the call at an appropriate interval.

from agentFactory import data_sources

client = data_sources.FileSource(configuration)
status = client.get_ingestion_status(source_id="<source-id>")
print(status["status"], status["ready"])
if status["errorMessage"]:
    print(status["errorMessage"])

File Data Source

Method	Description	Returns
`create(source_name, description, files)`	Creates a source from one or more local files.	Data-source result dictionary.
`edit(source_id, description)`	Updates the description.	Data-source result dictionary.
`remove(source_id)`	Removes the source.	Data-source result dictionary.
`get_ingestion_status(source_id)`	Checks ingestion progress.	Ingestion-status dictionary.

`create` parameter	Type	Description
`source_name`	string	Required display name.
`description`	string	Required description.
`files`	string, `pathlib.Path`, or sequence	Required local file path or paths. Each file must exist and be a regular file.

edit requires source_id and description; remove and get_ingestion_status require source_id.

from agentFactory import data_sources, sso

sso.login(configuration)
client = data_sources.FileSource(configuration)
result = client.create(
    source_name="Employee Handbook",
    description="Current handbook documents.",
    files=["/path/to/employee-handbook.pdf"],
)
status = client.get_ingestion_status(result["sourceId"])
print("Source ready:", status["ready"])

See Data Source Ingestion Status for status fields and values.

Database Data Source

create accepts connection details, a connection string, or a wallet. edit(source_id, description) changes the description; remove(source_id) removes the source. Each method returns the data-source result dictionary. Database sources do not have get_ingestion_status.

`create` parameter	Type	Required	Description
`source_name`	string	Yes	Display name.
`description`	string	Yes	Description.
`username`	string	Yes	Database user name.
`password`	string	Yes	Database password. Do not log it.
`connection_type`	string	No	`details` (default), `connectionString`, or `wallet`.
`connection_string`	string	Conditional	Connection string for `connectionString` mode.
`protocol`	string	Conditional	Database protocol for `details` mode.
`host`	string	Conditional	Database host for `details` mode.
`port`	integer	Conditional	Database port for `details` mode.
`service_name`	string	Conditional	Database service name for `details` mode.
`wallet_id`	string	Conditional	Existing wallet ID, when applicable.
`selected_tns_alias`	string	Conditional	TNS alias selected from the wallet, when applicable.
`selected_alias`	string	Conditional	Additional alias value required by some database configurations.
`wallet`	string, `pathlib.Path`, or sequence	Conditional	Local wallet file path or paths.
`add_semantic_knowledge_graph`	boolean	No	Enable semantic knowledge graph creation. Default: `False`.
`embedding_model`	string	No	Embedding model for semantic knowledge graph creation.

from agentFactory import data_sources

client = data_sources.DatabaseSource(configuration)
result = client.create(
    source_name="Sales Database",
    description="Database used for sales analysis.",
    username="<database-username>",
    password="<database-password>",
    connection_type="details",
    protocol="tcp",
    host="<database-host>",
    port=1521,
    service_name="<service-name>",
)
print(result["sourceId"])

For a wallet connection, use connection_type="wallet", selected_tns_alias="<tns-alias>", and wallet="/secure/path/to/wallet.zip" instead of host, port, protocol, and service name.

Web Data Source

Method	Description	Returns
`create(source_name, description, endpoint, depth=0, frequency_days=1, exclude_file_extensions=(), include_filters=(), exclude_filters=(), proxy_url=None)`	Creates a web crawl source.	Data-source result dictionary.
`edit(source_id, description, proxy_url="")`	Updates the description and proxy URL; an empty `proxy_url` clears the proxy.	Data-source result dictionary.
`remove(source_id)`	Removes the source.	Data-source result dictionary.
`get_ingestion_status(source_id)`	Checks ingestion progress.	Ingestion-status dictionary with the fields described for FileSource.

`create` parameter	Type	Required	Description
`source_name`	string	Yes	Display name.
`description`	string	Yes	Description.
`endpoint`	string	Yes	Starting URL for crawling.
`depth`	integer	No	Crawl depth from `0` through `10`, or `-1` for unlimited depth. Default: `0`.
`frequency_days`	number	No	Crawl interval from `0.1` through `8064` days. Default: `1`.
`exclude_file_extensions`	sequence of strings	No	File extensions to exclude.
`include_filters`	sequence of strings	No	URL or content filters to include.
`exclude_filters`	sequence of strings	No	URL or content filters to exclude.
`proxy_url`	string	No	Proxy URL for crawling.

from agentFactory import data_sources

client = data_sources.WebSource(configuration)
result = client.create(
    source_name="Product Documentation",
    description="Public product documentation.",
    endpoint="https://docs.example.com",
    depth=2,
    frequency_days=7,
    include_filters=["/guides/"],
)
print(client.get_ingestion_status(result["sourceId"])["ready"])

REST API Data Source

Method	Description	Returns
`create(source_name, description, definition_path)`	Creates a source from a local OpenAPI JSON definition.	Data-source result dictionary.
`edit(source_id, protocol=None, url=None, name=None, description=None)`	Updates one or more fields; at least one editable field is required.	Data-source result dictionary.
`remove(source_id)`	Removes the source.	Data-source result dictionary.

Parameter	Type	Description
`source_name`	string	Required for `create`; display name.
`description`	string	Required for `create`; description. Also optional for `edit`.
`definition_path`	string or `pathlib.Path`	Required for `create`; path to an existing OpenAPI JSON file.
`source_id`	string	Required for `edit` and `remove`.
`protocol`	string	Optional `edit` field; new protocol.
`url`	string	Optional `edit` field; new REST API URL.
`name`	string	Optional `edit` field; new REST API name.

from agentFactory import data_sources

client = data_sources.RestApiSource(configuration)
result = client.create(
    source_name="Inventory API",
    description="Internal inventory service.",
    definition_path="/path/to/inventory-openapi.json",
)
print(result["sourceId"])

Model Connection Clients

Use model_connections.LLM(configuration, timeout=120) for LLM connections or model_connections.Embedding(configuration, timeout=120) for embedding connections. configuration is required; timeout is the request timeout in seconds. Authenticate with sso.login(configuration) before creating, editing, or removing model connections. Listing supports an active SDK session.

Method	Description	Returns
`list(offset=0, limit=50)`	Lists visible connections of this model type.	Shared paginated list result.
`create(name, provider, model_id, ...)`	Creates a connection using the provider parameters below.	Dictionary containing `savedConfiguration`.
`edit(name, provider, model_id, ...)`	Updates a connection; supply its complete provider configuration.	Dictionary containing `savedConfiguration`.
`remove(name)`	Removes the named connection.	Dictionary with boolean `success`; optional `message` and `errorCode`.

Each list item includes id, name, provider, resourceType, isOwner, and actions. savedConfiguration includes the saved name, provider, non-secret connectionDetails, isActive, isPrimary, and available creation and update dates.

Create and Edit Parameters

LLM.create, LLM.edit, Embedding.create, and Embedding.edit accept the same parameters. The first three are required; other requirements depend on the provider and authentication mode.

Parameter	Type	Description
`name`	string	Required unique connection name. Also identifies the connection to edit or remove.
`provider`	string	Required provider name.
`model_id`	string	Required provider model ID.
`api_key`	string	Provider API key, when needed. Do not log it.
`base_url`	string	Base URL for a compatible provider.
`host`	string	Model service host.
`port`	integer	Model service port.
`deployment_name`	string	Provider deployment name.
`endpoint`	string	Provider service endpoint.
`compartment`	string	OCI compartment ID.
`authentication`	string	OCI or Google authentication mode.
`user`	string	OCI user ID for user authentication.
`fingerprint`	string	OCI API-key fingerprint.
`tenancy`	string	OCI tenancy ID.
`region`	string	OCI region.
`serving_mode`	string	OCI model serving mode.
`model_provider`	string	Provider-specific model-provider value.
`credentials_file`	string or `pathlib.Path`	OCI private-key file or Google service-account JSON file, when required.
`ca_file`	string or `pathlib.Path`	CA certificate for Private AI Services. An omitted value during edit retains the current certificate.

Provider	Supported connection types
`openai`, `openai_compatible`, `openrouter`, `private_ai_services`	LLM and embedding
`ollama`, `vllm`, `oci`, `google`	LLM and embedding
`anthropic`, `azure`	LLM only
`local`	Embedding only

For Google, use authentication="api_key" with api_key, or authentication="service_account" with a service-account JSON credentials_file. For OCI user authentication, provide authentication="user", user, and the required OCI credentials, including a private-key credentials_file. For OCI instance principals, use authentication="instance_principal" without user, fingerprint, tenancy, region, or credentials_file. Omit authentication for other providers.

LLM Connections

from agentFactory import model_connections, sso

sso.login(configuration)
client = model_connections.LLM(configuration)
result = client.create(
    name="Corporate OpenAI Model",
    provider="openai",
    model_id="<provider-model-id>",
    api_key="<provider-api-key>",
)
print(result["savedConfiguration"]["name"])

To update this connection, call client.edit with its name and the complete provider configuration:

updated = client.edit(
    name="Corporate OpenAI Model",
    provider="openai",
    model_id="<new-provider-model-id>",
    api_key="<provider-api-key>",
)
print(updated["savedConfiguration"]["name"])

Embedding Connections

from agentFactory import model_connections

client = model_connections.Embedding(configuration)
result = client.create(
    name="Corporate Embeddings",
    provider="openai",
    model_id="<provider-embedding-model-id>",
    api_key="<provider-api-key>",
)
print(result["savedConfiguration"]["name"])