Programmatic Usage

Integrate Omnigent into your scripts, applications, and CI pipelines. Start agent sessions, send them work, and return to the same conversations for follow-up tasks. You can also open saved sessions in the Web UI to review their progress and results.

• CLI: Run a task from the command line and receive the agent's response.
• Python SDK: Send messages and manage sessions from Python.
• REST API: Create sessions, read their history, and manage their lifecycle over HTTP.
• Automations: Run an agent on a recurring schedule and manage those runs over HTTP. See Automate recurring work.
• GitHub Actions: Run an agent in a CI workflow, such as a PR review. See Configure Omnigent in GitHub Actions.

Every session you start this way is an ordinary Omnigent session, so it gets the same Web UI, sharing, and sub-agent support as one you start by hand. For request fields and response schemas, see the API Reference.

omni run ./my-agent/ -p "Review the changes in the latest commit"

Omnigent session: http://127.0.0.1:6767/c/conv_abc123

import asyncio
from omnigent_client import OmnigentClient
 
async def main():
    async with OmnigentClient(
        base_url="http://127.0.0.1:6767",
        # For a server requiring a bearer token:
        # headers={"Authorization": "Bearer <access_token>"},
    ) as client:
        agent = await client.sessions.resolve_agent("claude-native-ui")
        runner_id = await client.sessions.resolve_online_runner(harness=agent.harness)
        if runner_id is None:
            raise RuntimeError("Connect a runner that supports native Claude Code first")
 
        session = await client.sessions.create_from_agent_id(agent.id, title="Code review")
        await client.sessions.bind_runner(session.id, runner_id=runner_id)
        print(session.id)
        print(f"http://127.0.0.1:6767/c/{session.id}")
 
asyncio.run(main())

omni host --server http://127.0.0.1:6767

curl -fsS http://127.0.0.1:6767/v1/agents \
  | jq -r '.data[] | select(.harness == "claude-native") | .id'

curl -fsS http://127.0.0.1:6767/v1/hosts \
  | jq '.hosts[] | {name, host_id}'

curl -fsS http://127.0.0.1:6767/v1/hosts \
  | jq -r '.hosts[] | select(.name == "<host-name>") | .host_id'

SESSION_ID=$(curl --fail-with-body http://127.0.0.1:6767/v1/sessions \
  -H 'Content-Type: application/json' \
  -d '{
    "agent_id": "ag_reviewer",
    "host_id": "host_example",
    "workspace": "/home/ci/my-repository",
    "title": "Review latest commit"
  }' | jq -er '.id')

curl --fail-with-body "http://127.0.0.1:6767/v1/sessions/$SESSION_ID" | jq

omni run ./my-agent/ --continue -p "Now check whether the tests cover those changes"

omni run ./my-agent/ --resume "<conversation_id>" -p "Explain the first finding"

import asyncio
from omnigent_client import OmnigentClient
 
async def main():
    async with OmnigentClient(base_url="http://127.0.0.1:6767") as client:
        await client.sessions.post_event("conv_abc123", {
            "type": "message",
            "data": {
                "role": "user",
                "content": [{"type": "input_text", "text": "tell me a joke"}],
            },
        })
 
asyncio.run(main())

curl --fail-with-body "http://127.0.0.1:6767/v1/sessions/$SESSION_ID/events" \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "message",
    "data": {
      "role": "user",
      "content": [{"type": "input_text", "text": "Review the changes in the latest commit"}]
    }
  }'

echo "http://127.0.0.1:6767/c/$SESSION_ID"

import asyncio
from omnigent_client import OmnigentClient
 
async def main():
    async with OmnigentClient(base_url="http://127.0.0.1:6767") as client:
        sessions = await client.sessions.list(limit=20, sort_by="updated_at")
        for session in sessions:
            print(session.id, session.title, session.status)
        session_id = "conv_abc123"
        session = await client.sessions.get(session_id)
        print(session.status)
        print(await client.sessions.list_items(session_id))
 
asyncio.run(main())

curl --fail-with-body "http://127.0.0.1:6767/v1/sessions?limit=20&sort_by=updated_at"

curl --fail-with-body "http://127.0.0.1:6767/v1/sessions/<session_id>/items"

omni run ./my-agent/ --fork "<conversation_id>"

await client.sessions.bind_runner(fork["id"], runner_id=runner_id)

curl --fail-with-body "http://127.0.0.1:6767/v1/sessions/$SESSION_ID/events" \
  -H 'Content-Type: application/json' \
  -d '{"type": "interrupt"}'

FORK_ID=$(curl --fail-with-body "http://127.0.0.1:6767/v1/sessions/$SESSION_ID/fork" \
  -H 'Content-Type: application/json' \
  -d '{"title": "Explore another approach"}' | jq -er '.id')

curl --fail-with-body -X PATCH "http://127.0.0.1:6767/v1/sessions/$SESSION_ID" \
  -H 'Content-Type: application/json' \
  -d '{"archived": true}' | jq

curl --fail-with-body -X PATCH "http://127.0.0.1:6767/v1/sessions/$SESSION_ID" \
  -H 'Content-Type: application/json' \
  -d '{"archived": false}' | jq

curl --fail-with-body -X DELETE "http://127.0.0.1:6767/v1/sessions/$SESSION_ID" | jq

Share a session

Use the permissions API to share a session on a reachable shared server. Your credentials need manage or owner access to the session, and the server's sharing settings must allow the requested access.

The examples use bearer-token authentication:

SERVER_URL="<server-url>"
SESSION_ID="<session-id>"
ACCESS_TOKEN="<access-token>"

For a specific user, level is 1 for read access, 2 to also send messages and interact with the session, or 3 to also manage sharing. Public access is always read-only (level: 1).

curl --fail-with-body -X PUT "$SERVER_URL/v1/sessions/$SESSION_ID/permissions" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"user_id": "<user-id>", "level": 1}'

curl --fail-with-body -X PUT "$SERVER_URL/v1/sessions/$SESSION_ID/permissions" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"user_id": "__public__", "level": 1}'

curl --fail-with-body "$SERVER_URL/v1/sessions/$SESSION_ID/permissions" \
  -H "Authorization: Bearer $ACCESS_TOKEN" | jq

curl --fail-with-body -X DELETE \
  "$SERVER_URL/v1/sessions/$SESSION_ID/permissions/__public__" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Send the recipient the session URL. A specific user must sign in with the identity you granted access to:

echo "$SERVER_URL/c/$SESSION_ID"

You can also let an agent share sessions through sys_session_share. Set agent_session_sharing: non-public in its agent configuration to allow sharing with users, or agent_session_sharing: public to also allow public grants. The tool accepts user_id, level ("read", "edit", or "manage"), and an optional session_id that defaults to the calling session. The caller's permissions and server sharing settings still apply.

Edit an installed agent's configuration

Agents you install on a server keep their config.yaml bundle server-side. Instead of re-uploading the whole bundle to change a description, prompt, model, harness, or MCP server, you can read the editable fields and send a partial update over the REST API. Only the agent's owner can read or edit its configuration, even when a session that uses the agent is shared.

Check the server advertises support first: GET /v1/info returns agent_config_edit: true when configuration editing is available. Older servers omit the field; treat that as unsupported. On servers that lack support, the endpoints below return 501.

SERVER_URL="http://127.0.0.1:6767"
AGENT_ID="<agent-id>"   # from GET /v1/agents

curl -fsS -i "$SERVER_URL/v1/agents/$AGENT_ID/config"

ETAG=$(curl -fsS -D - -o /dev/null "$SERVER_URL/v1/agents/$AGENT_ID/config" \
  | tr -d '\r' | awk 'tolower($1) == "etag:" { print $2 }')

curl --fail-with-body -X PATCH "$SERVER_URL/v1/agents/$AGENT_ID" \
  -H 'Content-Type: application/json' \
  -H "If-Match: $ETAG" \
  -d '{
    "description": "Reviews migrations",
    "instructions": "Check compatibility and rollback steps.",
    "mcp_servers": {
      "docs": {"url": "https://docs.example.com/mcp"},
      "old-tool": null
    }
  }' | jq

The body accepts these top-level fields. Unknown fields are rejected, and the agent's name and executor.type cannot change.

Within an MCP server patch:

• transport cannot change on an existing server. Managed registry servers (editable: false in the read response) are read-only and return 409.
• headers and env merge by key: a null value deletes that key, a null map clears every key, and {} preserves the map. Omit credentials you are not changing; "[REDACTED]" placeholders are rejected.
• args replaces the whole array; [] clears it.
• New servers are written as sidecar files under tools/mcp/<name>.yaml; existing declarations are edited in place. The same safety checks as the session MCP routes apply.

A few things to know:

• Only standard config.yaml bundles are editable. Other formats return 409 with the code agent_config_not_editable.
• Edited YAML loses its comments and formatting; untouched files keep their contents. The agent keeps its ID and gets a new version; a patch that changes nothing leaves the version unchanged.
• Sessions pick up the new configuration on their next turn. Active turns are not interrupted, and per-session overrides still take precedence.
• Re-uploading the bundle through the install API still replaces the whole bundle; use it when you need to change files the PATCH fields don't cover.

Automate recurring work

An automation runs an agent with a saved prompt on a recurring schedule, with no one at the keyboard. Each run starts a new session, or continues one kept session, so you can follow and review runs in the Web UI like any other session. The web UI calls these Automations; the API and agent tools call them scheduled tasks (/v1/scheduled-tasks).

You can create the same automation in three ways:

• REST API: create and manage automations from your own scripts. See Manage automations with the REST API.
• Agent tools: ask an agent to schedule its own follow-up work. See Schedule recurring agent runs.
• Web UI: use the Automations page. See Scheduled tasks in the Web UI.

Each automation belongs to the user who created it, and you can see only your own. Whichever way you create one, a host must be online when the automation runs, or the automation must use a fresh cloud sandbox for each run. The agent also needs credentials and tool permissions that work without a person approving requests.

Each run sends your prompt followed by a short note that tells the agent no one is watching. See Scheduled Tasks for the full configuration, and How a firing runs for the run sequence.

Manage automations with the REST API

Before you call these endpoints:

• Use your own user credentials, such as a session cookie or a CLI login bearer token. Machine client-credentials tokens can't access /v1/scheduled-tasks.
• Check that GET /v1/info returns automations_enabled: true. If it doesn't, every /v1/scheduled-tasks route returns 404.

SERVER_URL="http://127.0.0.1:6767"
# For a shared server, add -H "Authorization: Bearer $ACCESS_TOKEN" to each request.

TASK_ID=$(curl --fail-with-body "$SERVER_URL/v1/scheduled-tasks" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Weekday code review",
    "prompt": "Review the latest commit and report findings without editing files.",
    "rrule": "FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR;BYHOUR=9;BYMINUTE=0",
    "timezone": "America/Los_Angeles",
    "agent_id": "ag_reviewer",
    "host_id": "host_example",
    "workspace": "/home/ci/my-repository"
  }' | jq -er '.id')

curl --fail-with-body -X POST "$SERVER_URL/v1/scheduled-tasks/$TASK_ID/run"

curl --fail-with-body "$SERVER_URL/v1/scheduled-tasks/$TASK_ID/runs?limit=10" \
  | jq '.runs[] | {status, conversation_id, error_code}'

curl --fail-with-body "$SERVER_URL/v1/scheduled-tasks" \
  | jq '.scheduled_tasks[] | {id, name, state, next_run_at, last_run_status}'

curl --fail-with-body -X PATCH "$SERVER_URL/v1/scheduled-tasks/$TASK_ID" \
  -H 'Content-Type: application/json' \
  -d '{"state": "paused"}' | jq

curl --fail-with-body -X DELETE "$SERVER_URL/v1/scheduled-tasks/$TASK_ID"

The create request requires name, prompt, rrule, and agent_id. The schedule is an RFC 5545 recurrence rule, evaluated in timezone (UTC by default). See Recurrence rules for the minimum interval. These optional fields control each run:

Schedule recurring agent runs

Ask an agent to create a scheduled task when you want the same work repeated. Omnigent provides four built-in tools:

For example, replace the host name and repository path in this prompt:

Create a scheduled task named "Weekday code review". Every weekday at 9am
Asia/Singapore, run native Claude Code on host "my-host" in
/home/ci/my-repository. Ask it to review the latest commit and report findings
without editing files. Look up the agent and host IDs first.

The schedule uses this recurrence rule with timezone: "Asia/Singapore":

FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR;BYHOUR=9;BYMINUTE=0

You can later ask, "Move Weekday code review to 10am," or "Delete Weekday code review." The agent uses the list and update or delete tools to make the change.

Creating or updating a task from an agent always pauses for your approval before anything is saved, even when no policies are configured — review the agent, prompt, host, and permission settings in the prompt before accepting. Listing and deleting tasks do not ask. See Approval for create and update.

Start a session for each new ticket, message, or issue

Automations created from Jira, Slack, or GitHub trigger templates in the Web UI are ordinary scheduled tasks with a generated prompt. You can list, run, pause, and delete them with the same endpoints and tools. The templates check for new items on a schedule; they don't receive webhooks. To react to events that the templates don't cover, receive the event in your own service, then start a session and send it the work with POST /v1/sessions and POST /v1/sessions/{id}/events.

Let an agent manage other sessions

You can ask an agent to delegate work to another Omnigent agent. It uses built-in session tools to create a child conversation, send instructions, and read the results. These are tools the agent calls during a session; you don't need to write an API client to use them.

For example, send this prompt in an Omnigent session:

Find the native Claude Code agent and create a child session titled
"Review tests". Ask it to review the test coverage in this repository without
editing files. Read its findings and summarize the missing coverage for me.

The agent can use sys_agent_list to find the agent, then call sys_session_create with arguments like these:

{
  "agent_id": "<agent_id from sys_agent_list>",
  "title": "Review tests",
  "message": "Review the test coverage in this repository. Report missing coverage without editing files."
}

The returned conversation_id identifies the child. To continue its work, ask:

Ask the "Review tests" child session to prioritize its findings by risk.

By default, sys_session_list leaves out archived sessions. With include_archived: true, the global sessions view lists them too, and each row carries an archived field.

sys_session_send can write only to the calling session's direct children. For agents with named sub-agents, reusing the same agent and title continues that child conversation; a different title starts a separate one. Child sessions appear in the Web UI, where you can follow their progress.

Some agents bundle skills that coordinate this work for you. For example, Polly provides investigate, fanout, and cross-review.

API endpoints reference

These tables summarize the main endpoints for agents, sessions, and automations.

The server exposes these agent, host, and project endpoints. Replace {id} with an agent ID from GET /v1/agents.

The server exposes these session endpoints. Replace {id} with a session ID.

The server exposes these automation endpoints. Replace {id} with an automation ID from GET /v1/scheduled-tasks.

See the API Reference for request and response schemas and for other endpoints.