# ACI Python SDK
[](https://pypi.org/project/aci-sdk/)
The official Python SDK for the ACI (Agent-Computer Interface) by Aipolabs.
Currently in beta, breaking changes are expected.
The ACI Python SDK provides convenient access to the ACI REST API from any Python 3.10+
application.
## Documentation
The detailed documentation is available [here](https://aci.dev/docs).
## Installation
```bash
pip install aci-sdk
```
or with uv:
```bash
uv add aci-sdk
```
## Usage
ACI platform is built with agent-first principles. Although you can call each of the APIs below any way you prefer in your application, we strongly recommend trying the [Agent-centric features](#agent-centric-features) and taking a look at the [agent examples](https://github.com/aipotheosis-labs/aci-agents/tree/main/examples) to get the most out of the platform and to enable the full potential and vision of future agentic applications.
### Client
```python
from aci import ACI
client = ACI(
# it reads from environment variable by default so you can omit it if you set it in your environment
api_key=os.environ.get("ACI_API_KEY")
)
```
### Apps
#### Types
```python
from aci.types.apps import AppBasic, AppDetails
```
#### Methods
```python
# search for apps, returns list of basic app data, sorted by relevance to the intent
# all parameters are optional
apps: list[AppBasic] = client.apps.search(
intent="I want to search the web",
allowed_apps_only=False, # If true, only return apps that are allowed by the agent/accessor, identified by the api key.
include_functions=False, # If true, include functions (name and description) in the search results.
categories=["search"],
limit=10,
offset=0
)
```
```python
# get detailed information about an app, including functions supported by the app
app_details: AppDetails = client.apps.get(app_name="BRAVE_SEARCH")
```
### App Configurations
#### Types
```python
from aci.types.app_configurations import AppConfiguration
from aci.types.enums import SecurityScheme
```
#### Methods
```python
# Create a new app configuration
configuration = client.app_configurations.create(
app_name="GMAIL",
security_scheme=SecurityScheme.OAUTH2
)
```
```python
# List app configurations
# All parameters are optional
configurations: list[AppConfiguration] = client.app_configurations.list(
app_names=["GMAIL", "BRAVE_SEARCH"], # Filter by app names
limit=10, # Maximum number of results
offset=0 # Pagination offset
)
```
```python
# Get app configuration by app name
configuration: AppConfiguration = client.app_configurations.get(app_name="GMAIL")
```
```python
# Delete an app configuration
client.app_configurations.delete(app_name="GMAIL")
```
### Linked Accounts
#### Types
```python
from aci.types.linked_accounts import LinkedAccount, LinkedAccountWithCredentials
from aci.types.enums import SecurityScheme
```
#### Methods
```python
# Link an account
# Returns created LinkedAccount for API_KEY and NO_AUTH security schemes
# Returns authorization URL string for OAUTH2 security scheme (you need to finish the flow in browser to create the account)
result = client.linked_accounts.link(
app_name="BRAVE_SEARCH", # Name of the app to link to
linked_account_owner_id="user123", # ID to identify the owner of this linked account
security_scheme=SecurityScheme.API_KEY, # Type of authentication
api_key="your-api-key" # Required for API_KEY security scheme
)
# OAuth2 example (returns auth URL for user to complete OAuth flow in browser)
oauth_url = client.linked_accounts.link(
app_name="GMAIL",
linked_account_owner_id="user123",
security_scheme=SecurityScheme.OAUTH2,
# Optional parameter to redirect to a custom URL after the OAuth2 flow (default to https://platform.aci.dev)
# Note: the url need to be "https"
after_oauth2_link_redirect_url="https://<your website for your end users>"
)
# No-auth example
account = client.linked_accounts.link(
app_name="AGENT_SECRETS_MANAGER",
linked_account_owner_id="user123",
security_scheme=SecurityScheme.NO_AUTH
)
```
```python
# List linked accounts
# All parameters are optional
accounts = client.linked_accounts.list(
app_name="BRAVE_SEARCH", # Filter by app name
linked_account_owner_id="user123" # Filter by owner ID
)
```
```python
# Get a specific linked account by ID (note: linked_account_id is different from the linked_account_owner_id)
account = client.linked_accounts.get(linked_account_id=account_id)
```
```python
# Enable a linked account (note: linked_account_id is different from the linked_account_owner_id)
account = client.linked_accounts.enable(linked_account_id=account_id)
```
```python
# Disable a linked account (note: linked_account_id is different from the linked_account_owner_id)
account = client.linked_accounts.disable(linked_account_id=account_id)
```
```python
# Delete a linked account (note: linked_account_id is different from the linked_account_owner_id)
client.linked_accounts.delete(linked_account_id=account_id)
```
### Functions
#### Types
```python
from aci.types.functions import FunctionExecutionResult
from aci.types.enums import FunctionDefinitionFormat
```
#### Methods
```python
# search for functions, returns list of basic function data, sorted by relevance to the intent
# all parameters are optional
functions: list[dict] = client.functions.search(
app_names=["BRAVE_SEARCH", "TAVILY"],
intent="I want to search the web",
allowed_only=False, # If true, only returns functions of apps that are allowed by the agent/accessor, identified by the api key.
format=FunctionDefinitionFormat.OPENAI, # The format of the functions, can be OPENAI, ANTHROPIC, BASIC (name and description only)
limit=10,
offset=0
)
```
```python
# get function definition of a specific function, this is the schema you can feed into LLM
# the actual format is defined by the format parameter: OPENAI, ANTHROPIC, BASIC (name and description only)
function_definition: dict = client.functions.get_definition(
function_name="BRAVE_SEARCH__WEB_SEARCH",
format=FunctionDefinitionFormat.OPENAI
)
```
```python
# execute a function with the provided parameters
result: FunctionExecutionResult = client.functions.execute(
function_name="BRAVE_SEARCH__WEB_SEARCH",
function_arguments={"query": {"q": "what is the weather in barcelona"}},
linked_account_owner_id="john_doe"
)
if result.success:
print(result.data)
else:
print(result.error)
```
### Utility functions
#### to_json_schema
Convert a local python function to a LLM compatible tool schema, so you can use custom functions (tools) along with ACI.dev functions (tools).
```python
from aci import to_json_schema
# dummy function to test the schema conversion
def custom_function(
required_int: int,
optional_str_with_default: str = "default string",
) -> None:
"""This is a test function.
Args:
required_int: This is required_int.
optional_str_with_default: This is optional_str_with_default.
"""
pass
# for openai chat completions api
custom_function_openai_chat_completions = to_json_schema(custom_function, FunctionDefinitionFormat.OPENAI)
"""result:
{
"type": "function",
"function": {
"name": "custom_function",
"description": "This is a test function.",
"parameters": {
"properties": {
"required_int": {
"description": "This is required_int.",
"title": "Required Int",
"type": "integer"
},
"optional_str_with_default": {
"default": "default string",
"description": "This is optional_str_with_default.",
"title": "Optional Str With Default",
"type": "string"
}
},
"required": ["required_int"],
"title": "custom_function_args",
"type": "object",
"additionalProperties": False
}
}
}
"""
# alternative format: for openai responses api
custom_function_openai_responses = to_json_schema(custom_function, FunctionDefinitionFormat.OPENAI_RESPONSES)
# alternative format: for anthropic api
custom_function_anthropic = to_json_schema(custom_function, FunctionDefinitionFormat.ANTHROPIC)
# use the tool in a openai chat completion api
response = openai.chat.completions.create(
model="gpt-4o",
messages=[
{
"role": "system",
"content": "You are a helpful assistant with access to a variety of tools.",
},
],
tools=[custom_function_openai_chat_completions]
)
```
### Agent-centric features
The SDK provides a suite of features and helper functions to make it easier and more seamless to use functions in LLM powered agentic applications.
This is our vision and the recommended way of trying out the SDK.
#### Meta Functions and Unified Function Calling Handler
- A set of meta functions that can be used with LLMs as tools directly. Essentially, they are just the json schema version of some of the backend APIs of ACI.dev. They are provided so that your LLM/Agent can utlize some of the features of ACI.dev directly via function (tool) calling.
- A unified handler for function (tool) calls, which handles both the direct function calls (e.g., BRAVE_SEARCH__WEB_SEARCH) and the meta functions calls (e.g., ACISearchFunctions, ACIExecuteFunction).
```python
from aci.meta_functions import ACISearchFunctions, ACIExecuteFunction
from aci.types.enums import FunctionDefinitionFormat
# meta functions
tools = [
ACISearchFunctions.to_json_schema(FunctionDefinitionFormat.OPENAI),
ACIExecuteFunction.to_json_schema(FunctionDefinitionFormat.OPENAI),
]
# use the meta functions (tools) in a openai chat completion api
response = openai.chat.completions.create(
model="gpt-4o",
messages=[
{
"role": "system",
"content": "Can you help star aipotheosis-labs/aci github repo?",
},
],
tools=tools
)
```
```python
# unified function calling handler
tool_call = response.choices[0].message.tool_calls[0]
result = client.handle_function_call(
tool_call.function.name,
json.loads(tool_call.function.arguments),
linked_account_owner_id="john_doe",
allowed_only=True,
format=FunctionDefinitionFormat.OPENAI
)
```
Please see [agent examples](https://github.com/aipotheosis-labs/aci-agents?tab=readme-ov-file#2-agent-with-dynamic-tool-discovery-and-execution) for more advanced and complete examples.
Raw data
{
"_id": null,
"home_page": null,
"name": "aci-sdk",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "Aipolabs <support@aipolabs.xyz>",
"keywords": "ACI, API, Agent Computer Interface, Aipolabs, Aipotheosis Labs, Function Calling, LLM, MCP, Tool Calling",
"author": null,
"author_email": "Aipolabs <support@aipolabs.xyz>",
"download_url": "https://files.pythonhosted.org/packages/0a/89/ac08d1377ab1269ea094a61bf013241acbd4a0c39d9f65921bb432969d09/aci_sdk-1.0.0b4.tar.gz",
"platform": null,
"description": "# ACI Python SDK\n\n[](https://pypi.org/project/aci-sdk/)\n\nThe official Python SDK for the ACI (Agent-Computer Interface) by Aipolabs.\nCurrently in beta, breaking changes are expected.\n\nThe ACI Python SDK provides convenient access to the ACI REST API from any Python 3.10+\napplication.\n\n## Documentation\nThe detailed documentation is available [here](https://aci.dev/docs).\n\n## Installation\n```bash\npip install aci-sdk\n```\n\nor with uv:\n```bash\nuv add aci-sdk\n```\n\n## Usage\nACI platform is built with agent-first principles. Although you can call each of the APIs below any way you prefer in your application, we strongly recommend trying the [Agent-centric features](#agent-centric-features) and taking a look at the [agent examples](https://github.com/aipotheosis-labs/aci-agents/tree/main/examples) to get the most out of the platform and to enable the full potential and vision of future agentic applications.\n\n### Client\n```python\nfrom aci import ACI\n\nclient = ACI(\n # it reads from environment variable by default so you can omit it if you set it in your environment\n api_key=os.environ.get(\"ACI_API_KEY\")\n)\n```\n\n### Apps\n#### Types\n```python\nfrom aci.types.apps import AppBasic, AppDetails\n```\n\n#### Methods\n```python\n# search for apps, returns list of basic app data, sorted by relevance to the intent\n# all parameters are optional\napps: list[AppBasic] = client.apps.search(\n intent=\"I want to search the web\",\n allowed_apps_only=False, # If true, only return apps that are allowed by the agent/accessor, identified by the api key.\n include_functions=False, # If true, include functions (name and description) in the search results.\n categories=[\"search\"],\n limit=10,\n offset=0\n)\n```\n\n```python\n# get detailed information about an app, including functions supported by the app\napp_details: AppDetails = client.apps.get(app_name=\"BRAVE_SEARCH\")\n```\n\n### App Configurations\n#### Types\n```python\nfrom aci.types.app_configurations import AppConfiguration\nfrom aci.types.enums import SecurityScheme\n```\n\n#### Methods\n```python\n# Create a new app configuration\nconfiguration = client.app_configurations.create(\n app_name=\"GMAIL\",\n security_scheme=SecurityScheme.OAUTH2\n)\n```\n\n```python\n# List app configurations\n# All parameters are optional\nconfigurations: list[AppConfiguration] = client.app_configurations.list(\n app_names=[\"GMAIL\", \"BRAVE_SEARCH\"], # Filter by app names\n limit=10, # Maximum number of results\n offset=0 # Pagination offset\n)\n```\n\n```python\n# Get app configuration by app name\nconfiguration: AppConfiguration = client.app_configurations.get(app_name=\"GMAIL\")\n```\n\n\n```python\n# Delete an app configuration\nclient.app_configurations.delete(app_name=\"GMAIL\")\n```\n\n### Linked Accounts\n#### Types\n```python\nfrom aci.types.linked_accounts import LinkedAccount, LinkedAccountWithCredentials\nfrom aci.types.enums import SecurityScheme\n```\n\n#### Methods\n```python\n# Link an account\n# Returns created LinkedAccount for API_KEY and NO_AUTH security schemes\n# Returns authorization URL string for OAUTH2 security scheme (you need to finish the flow in browser to create the account)\nresult = client.linked_accounts.link(\n app_name=\"BRAVE_SEARCH\", # Name of the app to link to\n linked_account_owner_id=\"user123\", # ID to identify the owner of this linked account\n security_scheme=SecurityScheme.API_KEY, # Type of authentication\n api_key=\"your-api-key\" # Required for API_KEY security scheme\n)\n\n# OAuth2 example (returns auth URL for user to complete OAuth flow in browser)\noauth_url = client.linked_accounts.link(\n app_name=\"GMAIL\",\n linked_account_owner_id=\"user123\",\n security_scheme=SecurityScheme.OAUTH2,\n # Optional parameter to redirect to a custom URL after the OAuth2 flow (default to https://platform.aci.dev)\n # Note: the url need to be \"https\"\n after_oauth2_link_redirect_url=\"https://<your website for your end users>\"\n)\n\n# No-auth example\naccount = client.linked_accounts.link(\n app_name=\"AGENT_SECRETS_MANAGER\",\n linked_account_owner_id=\"user123\",\n security_scheme=SecurityScheme.NO_AUTH\n)\n```\n\n```python\n# List linked accounts\n# All parameters are optional\naccounts = client.linked_accounts.list(\n app_name=\"BRAVE_SEARCH\", # Filter by app name\n linked_account_owner_id=\"user123\" # Filter by owner ID\n)\n```\n\n```python\n# Get a specific linked account by ID (note: linked_account_id is different from the linked_account_owner_id)\naccount = client.linked_accounts.get(linked_account_id=account_id)\n```\n\n```python\n# Enable a linked account (note: linked_account_id is different from the linked_account_owner_id)\naccount = client.linked_accounts.enable(linked_account_id=account_id)\n```\n\n```python\n# Disable a linked account (note: linked_account_id is different from the linked_account_owner_id)\naccount = client.linked_accounts.disable(linked_account_id=account_id)\n```\n\n```python\n# Delete a linked account (note: linked_account_id is different from the linked_account_owner_id)\nclient.linked_accounts.delete(linked_account_id=account_id)\n```\n\n### Functions\n#### Types\n```python\nfrom aci.types.functions import FunctionExecutionResult\nfrom aci.types.enums import FunctionDefinitionFormat\n```\n\n#### Methods\n```python\n# search for functions, returns list of basic function data, sorted by relevance to the intent\n# all parameters are optional\nfunctions: list[dict] = client.functions.search(\n app_names=[\"BRAVE_SEARCH\", \"TAVILY\"],\n intent=\"I want to search the web\",\n allowed_only=False, # If true, only returns functions of apps that are allowed by the agent/accessor, identified by the api key.\n format=FunctionDefinitionFormat.OPENAI, # The format of the functions, can be OPENAI, ANTHROPIC, BASIC (name and description only)\n limit=10,\n offset=0\n)\n```\n\n```python\n# get function definition of a specific function, this is the schema you can feed into LLM\n# the actual format is defined by the format parameter: OPENAI, ANTHROPIC, BASIC (name and description only)\nfunction_definition: dict = client.functions.get_definition(\n function_name=\"BRAVE_SEARCH__WEB_SEARCH\",\n format=FunctionDefinitionFormat.OPENAI\n)\n```\n\n```python\n# execute a function with the provided parameters\nresult: FunctionExecutionResult = client.functions.execute(\n function_name=\"BRAVE_SEARCH__WEB_SEARCH\",\n function_arguments={\"query\": {\"q\": \"what is the weather in barcelona\"}},\n linked_account_owner_id=\"john_doe\"\n)\n\nif result.success:\n print(result.data)\nelse:\n print(result.error)\n```\n\n### Utility functions\n#### to_json_schema\nConvert a local python function to a LLM compatible tool schema, so you can use custom functions (tools) along with ACI.dev functions (tools).\n```python\nfrom aci import to_json_schema\n\n# dummy function to test the schema conversion\ndef custom_function(\n required_int: int,\n optional_str_with_default: str = \"default string\",\n) -> None:\n \"\"\"This is a test function.\n\n Args:\n required_int: This is required_int.\n optional_str_with_default: This is optional_str_with_default.\n \"\"\"\n pass\n\n# for openai chat completions api\ncustom_function_openai_chat_completions = to_json_schema(custom_function, FunctionDefinitionFormat.OPENAI)\n\"\"\"result:\n{\n \"type\": \"function\",\n \"function\": {\n \"name\": \"custom_function\",\n \"description\": \"This is a test function.\",\n \"parameters\": {\n \"properties\": {\n \"required_int\": {\n \"description\": \"This is required_int.\",\n \"title\": \"Required Int\",\n \"type\": \"integer\"\n },\n \"optional_str_with_default\": {\n \"default\": \"default string\",\n \"description\": \"This is optional_str_with_default.\",\n \"title\": \"Optional Str With Default\",\n \"type\": \"string\"\n }\n },\n \"required\": [\"required_int\"],\n \"title\": \"custom_function_args\",\n \"type\": \"object\",\n \"additionalProperties\": False\n }\n }\n}\n\"\"\"\n\n# alternative format: for openai responses api\ncustom_function_openai_responses = to_json_schema(custom_function, FunctionDefinitionFormat.OPENAI_RESPONSES)\n\n# alternative format: for anthropic api\ncustom_function_anthropic = to_json_schema(custom_function, FunctionDefinitionFormat.ANTHROPIC)\n\n# use the tool in a openai chat completion api\nresponse = openai.chat.completions.create(\n model=\"gpt-4o\",\n messages=[\n {\n \"role\": \"system\",\n \"content\": \"You are a helpful assistant with access to a variety of tools.\",\n },\n ],\n tools=[custom_function_openai_chat_completions]\n)\n```\n\n### Agent-centric features\n\nThe SDK provides a suite of features and helper functions to make it easier and more seamless to use functions in LLM powered agentic applications.\nThis is our vision and the recommended way of trying out the SDK.\n\n#### Meta Functions and Unified Function Calling Handler\n\n- A set of meta functions that can be used with LLMs as tools directly. Essentially, they are just the json schema version of some of the backend APIs of ACI.dev. They are provided so that your LLM/Agent can utlize some of the features of ACI.dev directly via function (tool) calling.\n\n- A unified handler for function (tool) calls, which handles both the direct function calls (e.g., BRAVE_SEARCH__WEB_SEARCH) and the meta functions calls (e.g., ACISearchFunctions, ACIExecuteFunction).\n\n```python\nfrom aci.meta_functions import ACISearchFunctions, ACIExecuteFunction\nfrom aci.types.enums import FunctionDefinitionFormat\n\n# meta functions\ntools = [\n ACISearchFunctions.to_json_schema(FunctionDefinitionFormat.OPENAI),\n ACIExecuteFunction.to_json_schema(FunctionDefinitionFormat.OPENAI),\n]\n\n# use the meta functions (tools) in a openai chat completion api\nresponse = openai.chat.completions.create(\n model=\"gpt-4o\",\n messages=[\n {\n \"role\": \"system\",\n \"content\": \"Can you help star aipotheosis-labs/aci github repo?\",\n },\n ],\n tools=tools\n)\n```\n\n```python\n# unified function calling handler\ntool_call = response.choices[0].message.tool_calls[0]\n\nresult = client.handle_function_call(\n tool_call.function.name,\n json.loads(tool_call.function.arguments),\n linked_account_owner_id=\"john_doe\",\n allowed_only=True,\n format=FunctionDefinitionFormat.OPENAI\n)\n```\n\nPlease see [agent examples](https://github.com/aipotheosis-labs/aci-agents?tab=readme-ov-file#2-agent-with-dynamic-tool-discovery-and-execution) for more advanced and complete examples.\n",
"bugtrack_url": null,
"license": null,
"summary": "The Python SDK for the Agent Computer Interface (ACI) by Aipotheosis Labs",
"version": "1.0.0b4",
"project_urls": null,
"split_keywords": [
"aci",
" api",
" agent computer interface",
" aipolabs",
" aipotheosis labs",
" function calling",
" llm",
" mcp",
" tool calling"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c49aa86493374cc1a4c0f1e55db9a2962dfb8ee6f1f149cf4f6d84d60cabd30d",
"md5": "f067de52b99d9cb691c2c2ecb04abc98",
"sha256": "7b644bdb91558ada198ec38f5835a9f6dd9a6e2db4b9d7cb0a25c51c4ec9deab"
},
"downloads": -1,
"filename": "aci_sdk-1.0.0b4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f067de52b99d9cb691c2c2ecb04abc98",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 32526,
"upload_time": "2025-08-20T16:45:50",
"upload_time_iso_8601": "2025-08-20T16:45:50.195053Z",
"url": "https://files.pythonhosted.org/packages/c4/9a/a86493374cc1a4c0f1e55db9a2962dfb8ee6f1f149cf4f6d84d60cabd30d/aci_sdk-1.0.0b4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0a89ac08d1377ab1269ea094a61bf013241acbd4a0c39d9f65921bb432969d09",
"md5": "382174c7a698308c92d0079742ccf986",
"sha256": "32c2a887d8ab6e7f6cfc4e0b7248ec8149e84c910a9ed432220e2d24d5be8e03"
},
"downloads": -1,
"filename": "aci_sdk-1.0.0b4.tar.gz",
"has_sig": false,
"md5_digest": "382174c7a698308c92d0079742ccf986",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 66566,
"upload_time": "2025-08-20T16:45:51",
"upload_time_iso_8601": "2025-08-20T16:45:51.270024Z",
"url": "https://files.pythonhosted.org/packages/0a/89/ac08d1377ab1269ea094a61bf013241acbd4a0c39d9f65921bb432969d09/aci_sdk-1.0.0b4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-20 16:45:51",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "aci-sdk"
}
JSON