Axernel SDK

from axernel import Axernel, models

axernel = Axernel()

axernel = Axernel(
    base_url="https://axernel.example.com",
    api_key="axk_...",
    timeout=60,
    max_retries=2,
)

from axernel import Axernel, models

axernel = Axernel()

project = axernel.projects.create(models.CreateProjectRequest(name="SDK quickstart"))
provider = axernel.model_providers.get_platform("openrouter-deepseek")
template = axernel.templates.get_platform("general-purpose")

agent = axernel.agents.create(
    project.id,
    models.CreateAgentRequest(
        name="Hasher",
        template_id=template.id,
        configuration=models.AgentConfiguration(
            harness=models.Harness.opencode,
            model_provider_id=provider.id,
            instructions="Use the shell to do what the task asks. Submit only the requested result.",
            contracts=models.Contracts(
                input=models.Contract(
                    schema_={
                        "type": "object",
                        "properties": {"task": {"type": "string"}},
                        "required": ["task"],
                        "additionalProperties": False,
                    }
                ),
                output=models.Contract(
                    schema_={
                        "type": "object",
                        "properties": {"digest": {"type": "string"}},
                        "required": ["digest"],
                        "additionalProperties": False,
                    }
                ),
            ),
            limits=models.AgentLimits(timeout_seconds=900, max_steps=100),
            artifacts=[],
        ),
    ),
)

session = axernel.sessions.create(
    project.id,
    models.CreateSessionRequest(agent_id=agent.id, checkpointing_enabled=True),
)

run = axernel.runs.create(
    session.id,
    models.CreateRunRequest(
        input=models.RunInput(
            data=models.JSONValue(
                {"task": "Compute the SHA-256 of the text 'hello axernel' with a shell command."}
            )
        )
    ),
)

result = axernel.runs.result(run.id)

print(result["digest"])

project = axernel.projects.create(
    models.CreateProjectRequest(
        name="Pull request automation",
        description="Agents that update repositories",
    )
)

page = axernel.projects.list(page=1, page_size=50)

for project in axernel.projects.iterate():
    print(project.id, project.name)

provider = axernel.model_providers.get_platform("openrouter-deepseek")
template = axernel.templates.get_platform("general-purpose")

provider = axernel.model_providers.create(
    models.CreateModelProviderRequest(
        name="Company inference gateway",
        protocol=models.ModelProviderProtocol.openai_compatible,
        base_url="https://models.example.com/v1",
        model_name="company/agent-model",
        token=os.environ["MODEL_PROVIDER_TOKEN"],
        pricing=models.ModelPricing(
            input_usd_per_million=0.25,
            output_usd_per_million=1.0,
            reasoning_usd_per_million=1.0,
            cache_read_usd_per_million=0.025,
            cache_write_usd_per_million=0.25,
        ),
    )
)

template = axernel.templates.create(
    models.CreateTemplateRequest(
        name="Coding environment",
        image_ref="registry.example.com/agents/coding@sha256:<digest>",
        environment_tools=[
            models.EnvironmentTool(name="git", description="Git command-line client"),
            models.EnvironmentTool(name="gh", description="GitHub command-line client"),
            models.EnvironmentTool(name="node", description="Node.js runtime"),
        ],
        preparation_timeout_seconds=600,
        sandbox_max_lifetime_seconds=86_400,
        sandbox_idle_timeout_seconds=1_800,
    )
)

import os

github_secret = axernel.secrets.create(
    project.id,
    models.CreateSecretRequest(
        name="GitHub service account",
        description="Repository access for coding agents",
        data=models.SecretData({"token": os.environ["GITHUB_TOKEN"]}),
    ),
)

axernel.secrets.update(
    project.id,
    github_secret.id,
    models.UpdateSecretRequest(
        data=models.SecretData({"token": os.environ["ROTATED_GITHUB_TOKEN"]}),
    ),
)

axernel.secrets.delete(project.id, github_secret.id)

input_contract = models.Contract(
    schema_={
        "type": "object",
        "properties": {
            "repository": {"type": "string"},
            "issueNumber": {"type": "integer", "minimum": 1},
            "task": {"type": "string"},
        },
        "required": ["repository", "issueNumber", "task"],
        "additionalProperties": False,
    }
)
output_contract = models.Contract(
    schema_={
        "type": "object",
        "properties": {
            "pullRequestUrl": {"type": "string"},
            "summary": {"type": "string"},
        },
        "required": ["pullRequestUrl", "summary"],
        "additionalProperties": False,
    }
)

capabilities = axernel.system.capabilities()
print(capabilities.schema_profile)

github_credential = models.CredentialSource(
    secret=models.SecretCredentialSource(
        secret_id=github_secret.id,
        key="token",
    )
)

agent = axernel.agents.create(
    project.id,
    models.CreateAgentRequest(
        name="Issue fixer",
        template_id=template.id,
        configuration=models.AgentConfiguration(
            harness=models.Harness.opencode,
            model_provider_id=provider.id,
            instructions=(
                "Read the requested issue, make the smallest correct change, "
                "run relevant validation, open a pull request, and submit its URL."
            ),
            contracts=models.Contracts(
                input=input_contract,
                output=output_contract,
            ),
            limits=models.AgentLimits(
                timeout_seconds=1800,
                max_steps=200,
            ),
            environment_credential_bindings={
                "GH_TOKEN": github_credential,
            },
            mcp_servers={
                "github": models.MCPServer(
                    remote=models.MCPRemote(
                        url="https://mcp.example.com/github",
                        authentication=models.MCPAuthentication(
                            type=models.MCPAuthenticationType.bearer,
                            credential=github_credential,
                        ),
                    )
                )
            },
            artifacts=[],
        ),
    ),
)

updated = axernel.agents.update(
    project.id,
    agent.id,
    models.UpdateAgentRequest(configuration=agent.configuration),
    expected_revision=agent.revision,
)

github_mcp = models.MCPServer(
    remote=models.MCPRemote(
        url="https://mcp.example.com/github",
        authentication=models.MCPAuthentication(
            type=models.MCPAuthenticationType.bearer,
            credential=models.CredentialSource(
                secret=models.SecretCredentialSource(
                    secret_id=github_secret.id,
                    key="token",
                ),
            ),
        ),
    )
)

github_mcp = models.MCPServer(
    remote=models.MCPRemote(
        url="https://mcp.example.com/github",
        authentication=models.MCPAuthentication(
            type=models.MCPAuthenticationType.bearer,
            credential=models.CredentialSource(
                run_request_credential="githubToken",
            ),
        ),
    )
)

remote = models.MCPRemote(
    url="https://mcp.example.com/tools",
    authentication=models.MCPAuthentication(
        type=models.MCPAuthenticationType.api_key,
        header_name="X-API-Key",
        credential=models.CredentialSource(run_request_credential="toolsApiKey"),
    ),
    request_headers=[
        models.MCPRequestHeader(
            name="X-Workspace-ID",
            value=models.CredentialSource(
                secret=models.SecretCredentialSource(
                    secret_id=workspace_secret.id,
                    key="id",
                ),
            ),
        )
    ],
)

tools_mcp = models.MCPServer(
    stdio=models.MCPStdio(
        command=[
            "env",
            "TOOLS_DEPLOYMENT_URL=https://tools.example.com",
            "node",
            "/opt/tools-mcp/index.js",
        ],
        environment_bindings={
            "TOOLS_TOKEN": models.CredentialSource(
                run_request_credential="toolsToken"
            )
        },
    )
)

specification = axernel.files.upload(
    project.id,
    "openapi.yaml",
    media_type="application/yaml",
)

reproduction = axernel.files.upload(
    project.id,
    "issue-285-reproduction.txt",
    media_type="text/plain",
)

session = axernel.sessions.create(
    project.id,
    models.CreateSessionRequest(
        agent_id=agent.id,
        checkpointing_enabled=True,
        attachments=[
            models.Attachment(
                file_id=specification.id,
                description="API specification for this conversation",
            )
        ],
    ),
    idempotency_key="create-conversation-42",
)

axernel.sessions.close(project.id, session.id)

request = models.CreateRunRequest(
    input=models.RunInput(
        data=models.JSONValue(
            {
                "repository": "https://github.com/acme/backend",
                "issueNumber": 285,
                "task": "Fix the issue and open a pull request.",
            }
        ),
        attachments=[
            models.Attachment(
                file_id=reproduction.id,
                description="Issue reproduction details needed only for this run",
            )
        ],
    ),
    timeout_seconds=1500,
    max_steps=150,
)

run = axernel.runs.create(
    session.id,
    request,
    idempotency_key="job-285-attempt-1",
)

run = axernel.runs.create(
    session.id,
    request,
    idempotency_key="job-285-attempt-1",
    credentials={
        "githubToken": os.environ["GITHUB_TOKEN"],
        "toolsToken": os.environ["TOOLS_TOKEN"],
    },
)

for event in axernel.runs.events(run.id):
    if event.type.value == "stream.error":
        print("stream error", event.data)
    else:
        # run.status, message.delta, tool.activity, harness.status
        print(event.type.value, event.data)

for event in axernel.runs.events(run.id, last_event_id=42):
    # Persist event.sequence after processing each harness event.
    pass

terminal_run = axernel.runs.wait(run.id, timeout=30 * 60, poll_interval=1)

if terminal_run.status == models.RunStatus.completed:
    print(terminal_run.response.value)
else:
    print(terminal_run.error)

result = axernel.runs.result(run.id)

print(result["pullRequestUrl"])

from axernel import RunNeedsInputError

try:
    result = axernel.runs.result(run.id)
except RunNeedsInputError as error:
    reply = axernel.runs.reply(
        error.run.session_id,
        error.run.id,
        {"repository_url": "https://github.com/acme/backend"},
        timeout_seconds=600,
        max_steps=100,
    )
    result = axernel.runs.result(reply.id)

artifacts = [
    models.ArtifactRequirement(
        name="report",
        file_name="report.pdf",
        media_type="application/pdf",
        required=True,
    )
]

completed = axernel.runs.wait(run.id)

for output in completed.artifact_outputs:
    if output.status == models.ArtifactOutputStatus.available and output.artifact_id:
        metadata = axernel.artifacts.get(output.artifact_id)
        file_name = metadata.path.split("/")[-1] or metadata.name
        axernel.artifacts.download_to(output.artifact_id, f"./{file_name}")

unauthenticated = Axernel(base_url="https://axernel.example.com")
auth = unauthenticated.auth.login(
    models.LoginRequest(
        email="[email protected]",
        password=os.environ["AXERNEL_PASSWORD"],
    )
)

authenticated = Axernel(
    base_url="https://axernel.example.com",
    api_key=auth.token,
)

page = axernel.agents.list(project.id, page=1, page_size=50)

for agent in axernel.agents.iterate(project.id):
    print(agent.id)

from axernel import APIError

try:
    axernel.agents.get(project.id, "missing")
except APIError as error:
    print(error.status_code, error.code, error.request_id, error.details)