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:

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