API Reference

API Reference#

Client#

class Jentic(config=None)#

Bases: object

High-level async client for the Jentic API Hub.

This class is opinionated but intentionally thin: it validates inputs, delegates all network traffic to jentic.lib.core_api.BackendAPI, and returns Pydantic models so you get autocompletion and type checking out-of-the-box.

Environment#

Unless you explicitly supply an AgentConfig the client loads configuration from environment variables via jentic.lib.cfg.AgentConfig.from_env().

The only required variable is JENTIC_AGENT_API_KEY – the Agent API key you copy from the Jentic dashboard. Example:

export JENTIC_AGENT_API_KEY=ak_live_*******

All other values (JENTIC_ENVIRONMENT etc.) default sensibly for production.

Examples#

Minimal search → load → execute loop

import asyncio
from jentic import Jentic, SearchRequest, LoadRequest, ExecutionRequest

async def main() -> None:
    client = Jentic()
    search = await client.search(SearchRequest(query="send an message via discord"))
    op_id  = search.results[0].id

    # Load the operation, view inputs and outputs
    response = await client.load(LoadRequest(ids=[op_id]))
    tool_info = response.tool_info[op_id]

    # Execute the operation
    result = await client.execute(ExecutionRequest(id=op_id, inputs={"to":"bob@example.com","body":"Hi"}))

    # Print the result
    print (result.status_code)
    print (result.output)

asyncio.run(main())

Notes for advanced users#

If you need fully-specified LLM tools, see jentic.lib.agent_runtime.AgentToolManager instead.

Parameters#

configAgentConfig | None, optional: Pre-validated agent configuration. If None the instance resolves config from the current environment.

async execute(request)#

Execute a previously-loaded operation or workflow.

ExecutionRequest.id must be the exact UUID you obtained from the search results – the SDK figures out whether it is an operation or a workflow.

Return type:: ExecuteResponse

Parameters#

requestExecutionRequest

id – UUID prefixed with op_ or wf_
inputs – dict that satisfies the JSON schema returned by load()

Returns#

ExecuteResponse

success is True the output field contains the tool’s returned data (often JSON). On failure the error field is populated and success is False.
status_code – HTTP status code of the response

Example#

>>> req = ExecutionRequest(id="op_123", inputs={"text":"hello"})
>>> resp = await client.execute(req)
>>> resp.success
True

async list_apis()#

Return every API the current agent is authorised to see.

Return type:: list[APIIdentifier]

Returns#

list[APIIdentifier]: Each identifier contains the vendor, name and version.

async load(request)#

Fetch JSON schemas & auth metadata for given IDs.

Call this after a successful search and before execute so you can validate user input and inform the LLM of required environment variables.

Return type:: LoadResponse

Parameters#

requestLoadRequest: ids should contain one or many UUIDs returned by search.

Returns#

LoadResponse

tool_info - mapping id -> tool info

Tip#

The returned object is compatible with jentic.lib.agent_runtime.AgentToolManager so you can write the JSON to jentic.json and immediately generate tool definitions.

async search(request)#

Full-text search across APIs, operations and workflows.

The query string supports natural-language phrases – the backend uses semantic search to find best matches. Results are automatically scoped to the APIs your agent key grants access to.

Return type:: SearchResponse

Parameters#

requestSearchRequest: Pass an instance for maximum control (limit, keywords, filter list of APIs). For convenience you can also call await client.search(SearchRequest(query="...")).

Returns#

SearchResponse

results – ranked list of operations & workflows
total_count – total hits before pagination
query – the original query string

Examples#

>>> sr = SearchRequest(query="create a Trello card", limit=10)
>>> hits = await client.search(sr)
>>> hits.results[0].summary
'Create a new card in a Trello list'

Configuration#

class AgentConfig(agent_api_key, user_agent='Jentic/1.0 Agent (Python)', environment='prod', connect_timeout=10.0, read_timeout=10.0, write_timeout=120.0, pool_timeout=120.0, max_connections=5, max_keepalive_connections=5)#

Bases: object

agent_api_key: str#

connect_timeout: float = 10.0#

property core_api_url: str#

environment: str = 'prod'#

classmethod from_env()#

Create an AgentConfig from environment variables.

Raises:

MissingAgentKeyError – If the JENTIC_AGENT_API_KEY environment variable is not set.
JenticEnvironmentError – If the JENTIC_ENVIRONMENT environment variable is not set or is invalid.

Return type:

AgentConfig

max_connections: int = 5#

max_keepalive_connections: int = 5#

pool_timeout: float = 120.0#

read_timeout: float = 10.0#

user_agent: str = 'Jentic/1.0 Agent (Python)'#

write_timeout: float = 120.0#

Models#

class APIIdentifier(**data)#

Bases: BaseModel

Canonical identifier for an API as returned by Jentic.list_apis().

field api_name: str | None = None#: API name (set when targeting a specific API; otherwise None)

field api_vendor: str [Required]#: Vendor domain, e.g. ‘hubapi.com’

field api_version: str | None = None#: Version string (set when targeting a specific version; otherwise None)

class SearchRequest(**data)#

Bases: BaseModel

Parameters accepted by Jentic.search().

field apis: list[str] | None = None#: Optional list of API names to restrict the search to

field filter_by_credentials: bool = True#: When True, hide results the agent lacks credentials for

field keywords: list[str] | None = None#: Optional list of keywords used to boost semantic search

field limit: int = 5#: Maximum number of results to return

field query: str [Required]#: Free-text query string (natural language)

class SearchResponse(**data)#

Bases: BaseModel

Return value of Jentic.search().

field query: str [Required]#: Echo of the original search string

field results: list[SearchResult] [Optional]#: Rank-ordered list of operations and workflows that match the query

field total_count: int = 0#: Total number of hits

class LoadRequest(**data)#

Bases: BaseModel

Request model for Jentic.load().

field ids: list[str] | None = None#: List of operation/workflow UUIDs to load

to_dict()#

Return type:: dict[str, Any]

class LoadResponse(**data)#

Bases: BaseModel

Return value of Jentic.load().

classmethod from_get_files_response(get_files_response)#

Return type:: LoadResponse

field tool_info: dict[str, OperationDetail | WorkflowDetail | None] [Optional]#: Mapping of every requested UUID to its detailed schema

class ExecutionRequest(**data)#

Bases: BaseModel

Payload expected by Jentic.execute().

field id: str [Required]#: UUID of the operation/workflow to execute (op_… or wf_…)

field inputs: Dict[str, Any] [Optional]#: Input object matching the JSON schema returned by Jentic.load()

to_dict()#

Return type:: dict[str, Any]

class ExecuteResponse(**data)#

Bases: BaseModel

Return value of Jentic.execute().

field error: str | None = None#: Error message when success is False

field inputs: dict[str, Any] | None = None#: Echo of the original inputs (useful for debugging)

field output: Any | None = None#: Raw output produced by the operation/workflow (if any)

field status_code: int [Required]#: HTTP status code for the execution

field step_results: dict[str, Any] | None = None#: Per-step execution traces when the backend provides them

field success: bool [Required]#: True when the remote execution succeeded

API Reference

Contents

API Reference#

Client#

Environment#

Examples#

Notes for advanced users#

Parameters#

Parameters#

Returns#

Example#

Returns#

Parameters#

Returns#

Tip#

Parameters#

Returns#

Examples#

Configuration#

Models#