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 -> Paginated[AgentConfiguration]
    page = await sdk.agents.list()
    for agent in page.items:
        print(agent.id, agent.name, agent.model.model_name)

    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

Every API method is typed via the pydantic models re-exported from persona-models (e.g. AgentConfiguration, Project, Mission, ...). Write methods accept either a model instance or a plain dict; read methods always return the parsed model (or Paginated[...] for list endpoints).

from persona_sdk import AgentConfiguration, ModelConfiguration

# Create an agent from a typed model
agent = await sdk.agents.create(
    AgentConfiguration(
        name="my-agent",
        model=ModelConfiguration(model_name="gpt-4o"),
    )
)

# Read -> AgentConfiguration
fetched = await sdk.agents.get(agent.id)

# Update (mutate the model and send it back)
fetched.name = "renamed-agent"
await sdk.agents.update(agent.id, fetched)

# Delete
await sdk.agents.delete(agent.id)

A plain dict is still accepted for backwards compatibility:

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

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 -> AgentConfiguration
architect = await sdk.agents.get_architect()

Pagination

List endpoints return a Paginated[<Model>] with typed .items, .total, .page and .size:

page = await sdk.agents.list(keyword="bot", page=1, size=20)
# page.items  -> list[AgentConfiguration]
# page.total  -> 42
# page.page   -> 1
# page.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