persona-sdk-python 0.2.16

Async Python SDK for the Persona AI platform

persona-sdk-python

Async Python SDK for the Persona AI platform.

Installation

pip install persona-sdk-python

Or with uv:

uv add persona-sdk-python

Requirements: Python 3.10+

Quick start

import asyncio
from persona_sdk import PersonaSdk


async def main():
    sdk = PersonaSdk(
        base_url="https://persona.applica.guru/api",
        auth="prs_your_project_api_key",
    )

    # List agents in your project
    agents = await sdk.agents.list()
    print(agents)

    await sdk.close()


asyncio.run(main())

Authentication

The SDK supports two authentication methods via the auth parameter.

API key (default)

A plain string is wrapped automatically in ApiKeyAuthenticationProvider and sent as the x-persona-apikey header. Accepts:

• Master key (full admin access)
• Project API key (prs_...)
• Agent API key (prs_ag_...)

from persona_sdk import PersonaSdk

sdk = PersonaSdk(
    base_url="https://persona.applica.guru/api",
    auth="prs_your_project_api_key",
)

IAM Bearer token

For applications that authenticate users via IAM, pass a BearerTokenAuthenticationProvider with a valid JWT:

from persona_sdk import PersonaSdk, BearerTokenAuthenticationProvider

sdk = PersonaSdk(
    base_url="https://persona.applica.guru/api",
    auth=BearerTokenAuthenticationProvider(iam_jwt_token),
)

The token is sent as the Authorization: Bearer <token> header. The server validates it via the IAM service and resolves the user's project automatically.

Custom provider

Implement your own provider by subclassing AuthenticationProvider:

from persona_sdk import AuthenticationProvider

class MyProvider(AuthenticationProvider):
    def headers(self) -> dict[str, str]:
        return {"x-custom-header": "value"}

    def credentials(self) -> str:
        return "my-credentials"

Available APIs

The PersonaSdk instance exposes one client per resource:

Attribute	Description
sdk.agents	Agent management (CRUD, voices, AI instructions, architect)
sdk.projects	Project management and subscriptions
sdk.sessions	Sessions, messages, usage
sdk.knowledge_bases	Knowledge bases, documents, chunk search
sdk.workflows	Workflows, executions, queues
sdk.triggers	Triggers and trigger executions
sdk.missions	Missions (generate, execute, stop, continue)
sdk.features	Feature templates and MCP tools
sdk.credentials	OAuth credentials and authorization
sdk.service_prices	Service pricing

Each API method is fully async. Always close the SDK when done to release the underlying HTTP connection pool:

sdk = PersonaSdk(
    base_url="https://persona.applica.guru/api",
    auth="prs_your_api_key",
)
try:
    agents = await sdk.agents.list()
finally:
    await sdk.close()

CRUD example

# Create an agent
agent = await sdk.agents.create({
    "name": "my-agent",
    "model": {"modelName": "gpt-4o"},
})

# Read
fetched = await sdk.agents.get(agent["id"])

# Update
fetched["name"] = "renamed-agent"
await sdk.agents.update(agent["id"], fetched)

# Delete
await sdk.agents.delete(agent["id"])

AI System Instructions Generation

Generate system instructions for an agent using the project's AI architect:

# Generate from a description
instructions = await sdk.agents.generate_system_instructions(
    "Create a customer support agent that handles billing inquiries"
)

# Multi-turn refinement with session ID
instructions = await sdk.agents.generate_system_instructions(
    "Add a rule to always ask for the order number first",
    session_id="my-session-id",
)

# Get the project's architect agent configuration
architect = await sdk.agents.get_architect()

Pagination

List endpoints accept keyword, page, and size:

result = await sdk.agents.list(keyword="bot", page=1, size=20)
# {
#   "items": [...],
#   "total": 42,
#   "page": 1,
#   "size": 20
# }

Workflows

If your workflows service runs on a different host, pass workflows_url:

sdk = PersonaSdk(
    base_url="https://persona.applica.guru/api",
    auth="prs_...",
    workflows_url="https://persona.applica.guru/workflows",
)

# Execute a workflow
result = await sdk.workflows.execute(
    workflow_id="wf-123",
    data={"input": "value"},
)

Runners

For higher-level abstractions, the SDK provides runners:

from persona_sdk import PersonaClient
from persona_sdk.runners import AgentRunner, invoke_tool, retrieve_resource

client = PersonaClient(
    base_url="https://persona.applica.guru/api",
    auth="prs_...",
)

# Run an agent in an existing session
runner = AgentRunner(client=client, agent_id="agent-1", session_code="sess-1")
response = await runner.run("Hello, agent!")

# Invoke an MCP tool directly
result = await invoke_tool(
    client=client,
    mcp_server_name="my-mcp",
    transport=...,
    tool_name="search",
    args={"query": "hello"},
)

Proxy support

sdk = PersonaSdk(
    base_url="https://persona.applica.guru/api",
    auth="prs_...",
    proxy="http://proxy.local:8080",
)

License

Proprietary — © Applica Software Guru