Create an agent

An agent’s name can contain letters, digits, hyphens and underscores. It must be unique in the organization.

Create an instructions agent

Instructions are a task in plain English. A model works through them on the phone. Add an output_schema when you want a structured result.

Dashboard
CLI
Python SDK
Go SDK
REST API

The dashboard makes an agent from a run:

Open Agents and click Create agent. This opens Run a task.
Describe the task, for example: “Open Settings, go to About phone, and report the Android version exactly as shown.” Then start the run.
When the run has ended, click Save as agent on the run. See Save a run as an agent.

To set a Result schema, the Model or the limits, open the agent and click Edit.

axilio agents create android-version \
  --instructions "Open Settings, go to About phone, and report the Android version exactly as shown."

--model picks the model. Leave it out for the platform default.

from axilio.platform import Client

client = Client()
agent = client.agents.create(
    name="android-version",
    instructions="Open Settings, go to About phone, and report the Android version exactly as shown.",
)
print(agent.id)

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    platformgo "github.com/axilioai/platform-go"
    "github.com/axilioai/platform-go/client"
    "github.com/axilioai/platform-go/option"
)

func main() {
    api := client.NewClient(
        option.WithAPIKey(os.Getenv("AXILIO_API_KEY")),
        option.WithBaseURL("https://api.axilio.ai/api/v1"),
    )
    instructions := "Open Settings, go to About phone, and report the Android version exactly as shown."
    agent, err := api.Agents.Create(context.Background(), &platformgo.AgentCreateRequest{
        Name:         "android-version",
        Instructions: &instructions,
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(agent.ID)
}

REST API References:

Create an agent: POST /agents

Examples use Bash. To run them in PowerShell, see Run the curl examples on Windows.

curl --silent --show-error --fail-with-body \
  --request POST \
  --url https://api.axilio.ai/api/v1/agents \
  --header "X-Axilio-Api-Key: $AXILIO_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "android-version",
    "instructions": "Open Settings, go to About phone, and report the Android version exactly as shown.",
    "output_schema": {
      "type": "object",
      "properties": {"android_version": {"type": "string"}},
      "required": ["android_version"]
    }
  }'

Create a code agent

A code agent runs a Python script with no model. The script drives phone, reads its inputs from variables and reports its result with run.done. See What a run’s code can use.

search.py

phone.locator(query="the search box").fill(variables.get("query", "axilio"))
phone.get_by_text("Search").tap()
run.done({"searched": True})

Dashboard
CLI
REST API

The dashboard makes an agent from a run, so a code agent starts as a saved run or as an existing agent you change:

Save a run’s script: on an ended run, click Save as agent and choose to save the script.
Change an existing agent to code: open the agent, click Edit and choose Code. Paste the script under Script, choose what happens When a step fails (Fail the run, Ask a person or Repair it), and save.

axilio agents create search-flow --code search.py

--code saves the file as revision 1. Leave out both --code and --instructions to create an empty agent and push code later. The CLI caps code files at 256 KiB.

REST API References:

Create an agent: POST /agents

Examples use Bash. To run them in PowerShell, see Run the curl examples on Windows.

jq -n --rawfile code search.py \
  '{name:"search-flow", code:$code, on_failure:"ask"}' |
  curl --silent --show-error --fail-with-body \
    --request POST \
    --url https://api.axilio.ai/api/v1/agents \
    --header "X-Axilio-Api-Key: $AXILIO_API_KEY" \
    --header "Content-Type: application/json" \
    --data-binary @-

Send instructions or code, not both. A name already used in the organization returns 409. An unsupported model or an invalid output schema returns 400.

Handle a failed step

A code revision’s on_failure decides what a run does when a step fails, for example when an element can’t be found:

`on_failure`	What happens
`fail` (default)	The run fails, with the reason in `error`.
`ask`	The run pauses with reason `step_check_failed`. A person can fix the screen in the live view, then resume with `retry` to run the script again, or `complete` to end the run with their own result. See Answer a paused run.
`repair`	The model takes over in the same run. It finishes the task from the current screen, so the run can still succeed, and proposes a fixed script as a new revision.

A repaired run has repair.repaired: true and, when it proposed a fix, repair.proposed_revision_id. The proposed revision has proposal_state: "waiting" and is not used until a person promotes it. Repair time and model steps count against the run’s limits and are billed like any model step.

Save a run as an agent

Save an ad hoc run as an agent once it has ended. With from: "task" (the default), the run’s task becomes an instructions revision. With from: "script", the code the run executed becomes a code revision. The run’s model, output schema and limits fill in any setting you leave out.

Dashboard
REST API

Open the run from Runs.
Click Save as agent. It shows on a run that has ended and wasn’t started from a saved agent.
Enter a name and choose whether to save the task or the script.

REST API References:

Create an agent: POST /agents

curl --silent --show-error --fail-with-body \
  --request POST \
  --url https://api.axilio.ai/api/v1/agents \
  --header "X-Axilio-Api-Key: $AXILIO_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"name": "android-version-script", "source_run_id": "run_123", "from": "script"}'

Pull and push code

Each push adds a revision, which becomes the one runs use.

Dashboard
CLI
REST API

Open the agent from Agents and click Edit.
Change the instructions or the script.
Save. The change becomes a new version.

axilio agents pull agent_123 --out search.py
# Edit search.py.
axilio agents push agent_123 search.py --message "handle sign-in"

pull prints the code to stdout without --out. An agent whose current revision is instructions has no code to pull.

REST API References:

Get an agent: GET /agents/{agent_id}
Get a revision: GET /agents/{agent_id}/revisions/{revision_id}
Add a revision: POST /agents/{agent_id}/revisions

Examples use Bash. To run them in PowerShell, see Run the curl examples on Windows.Read the agent’s current_revision_id, then fetch that revision’s code or instructions:

REVISION_ID=$(curl --silent --show-error --fail-with-body \
  --url https://api.axilio.ai/api/v1/agents/agent_123 \
  --header "X-Axilio-Api-Key: $AXILIO_API_KEY" | jq -r .current_revision_id)

curl --silent --show-error --fail-with-body \
  --url "https://api.axilio.ai/api/v1/agents/agent_123/revisions/$REVISION_ID" \
  --header "X-Axilio-Api-Key: $AXILIO_API_KEY" | jq -r .code > search.py

Add a revision. kind is code or instructions:

jq -n --rawfile code search.py \
  '{kind:"code", code:$code, message:"handle sign-in", on_failure:"repair"}' |
  curl --silent --show-error --fail-with-body \
    --request POST \
    --url https://api.axilio.ai/api/v1/agents/agent_123/revisions \
    --header "X-Axilio-Api-Key: $AXILIO_API_KEY" \
    --header "Content-Type: application/json" \
    --data-binary @-

An agent can switch kind: add an instructions revision to a code agent, or the reverse. Revisions are never changed or removed.

Roll back or promote a revision

A rollback copies an earlier revision forward as the newest one, so history only grows. Promoting makes a repair’s proposed fix the current revision.

Dashboard
CLI
REST API

Open the agent, click Edit, and open Version history.
Select a version to read it.
Click Restore to roll back to it, or Use this fix on a proposed fix.

axilio agents revisions agent_123
axilio agents rollback agent_123 rev_456

The CLI doesn’t promote proposed fixes yet. Use the Dashboard or the REST API.

REST API References:

List an agent’s revisions: GET /agents/{agent_id}/revisions
Roll an agent back to an earlier revision: POST /agents/{agent_id}:rollback
Promote a proposed fix: POST /agents/{agent_id}/revisions/{revision_id}:promote

Examples use Bash. To run them in PowerShell, see Run the curl examples on Windows.

curl --silent --show-error --fail-with-body \
  --url "https://api.axilio.ai/api/v1/agents/agent_123/revisions?limit=20" \
  --header "X-Axilio-Api-Key: $AXILIO_API_KEY"

curl --silent --show-error --fail-with-body \
  --request POST \
  --url "https://api.axilio.ai/api/v1/agents/agent_123:rollback" \
  --header "X-Axilio-Api-Key: $AXILIO_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"revision_id": "rev_456"}'

curl --silent --show-error --fail-with-body \
  --request POST \
  --url "https://api.axilio.ai/api/v1/agents/agent_123/revisions/rev_789:promote" \
  --header "X-Axilio-Api-Key: $AXILIO_API_KEY"

Promoting returns 409 when the revision is not a fix waiting to be promoted, or when the agent has moved on from the revision the repaired run ran. Such a fix reads proposal_state: "superseded".

Change settings or delete an agent

PATCH /agents/{agent_id} changes the name, model, output schema, limits and data settings. Fields you leave out keep their values, and output_schema: null clears the schema. Instructions and code change only through revisions. Deleting an agent removes it and its revisions, and cancels its schedules’ runs that haven’t started. Its past runs stay in the run list.

CLI
REST API

axilio agents get agent_123
axilio agents delete agent_123 --yes

REST API References:

Update an agent: PATCH /agents/{agent_id}
Delete an agent: DELETE /agents/{agent_id}

curl --silent --show-error --fail-with-body \
  --request PATCH \
  --url https://api.axilio.ai/api/v1/agents/agent_123 \
  --header "X-Axilio-Api-Key: $AXILIO_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"max_steps": 100, "recording_enabled": true}'

curl --silent --show-error --fail-with-body \
  --request DELETE \
  --url https://api.axilio.ai/api/v1/agents/agent_123 \
  --header "X-Axilio-Api-Key: $AXILIO_API_KEY"

Get Started

Phones and Sessions

Agents and Runs

Files

Webhooks

Observability

Telemetry

Usage

Billing

Organization

Reference

Create an agent

Create an instructions agent

Create a code agent

Handle a failed step

Save a run as an agent

Pull and push code

Roll back or promote a revision

Change settings or delete an agent

Next steps

Run the agent

Schedule the agent

​Create an instructions agent

​Create a code agent

​Handle a failed step

​Save a run as an agent

​Pull and push code

​Roll back or promote a revision

​Change settings or delete an agent

​Next steps

Run the agent

Schedule the agent

Create an instructions agent

Create a code agent

Handle a failed step

Save a run as an agent

Pull and push code

Roll back or promote a revision

Change settings or delete an agent

Next steps