Your first agent in five minutes

1. Install the SDK

pip install agentway

Requires Python 3.11+. Its only dependency is httpx.

2. Create a project and a scope

In the dashboard, create a project. You'll see a public id on the project page that looks like this:

aw_x7k2m9p4qa

Copy it — it goes in your agent's source. Then create a scope. A scope is a department: name it whatever matches how you think about your agents (data, backend, support).

3. Generate a scope key

On the scope, click Generate key. You'll get something like ak_7f3a91c4e8b2…

Copy it now. Only a hash is stored, so it can never be shown again. If you lose it, revoke it and generate another.

Put it in your agent's environment:

AGENTWAY_API_KEY=ak_7f3a91c4e8b2...

One key covers every agent in that scope. Deploy twenty agents with the same key and they'll each register themselves — there is no per-agent setup step.

4. Wire up your loop

Here's a typical agent before AgentWay:

def main():
    while True:
        invoice = fetch_next_invoice()
        if not invoice:
            time.sleep(30)
            continue
        process(invoice)

And after:

from agentway import Agent

def main():
    agent = Agent(
        project_id="aw_x7k2m9p4qa",
        scope="data",
        slug="invoice-processor",
        name="Invoice Processor",
    )

    while agent.running():          # was: while True
        invoice = fetch_next_invoice()
        if not invoice:
            agent.note("no invoices queued")
            time.sleep(30)
            continue

        agent.working(f"processing {invoice.id}")
        process(invoice)
        agent.done()

Three changes:

• Agent(...) — declares who this agent is. It registers itself on the first run.
• while agent.running() — the heartbeat, the pause check, and directive pickup, in one request per iteration.
• agent.working(...) / done() — what shows on the dashboard. Free: it rides along with the next heartbeat rather than making its own request.

5. Run it

python worker.py

Open your dashboard. The agent appears on the canvas inside its scope, with its current activity updating as it works.

6. Optional: join the scope tree

The tree is how agents in a scope share what they learn. Create a branch on the scope in the dashboard — pipelines, say — then declare it in your agent:

agent = Agent(
    project_id="aw_x7k2m9p4qa",
    scope="data",
    slug="invoice-processor",
    name="Invoice Processor",
    branches=["pipelines"],
)

while agent.running():
    process_one_invoice()

    # tell colleagues something they need to know
    agent.write(
        "Supplier ACME changed its PO number format",
        details="Now PO-2024-xxxx. Older parsing rejects them.",
    )

    # read what they wrote since last time
    for entry in agent.catch_up():
        print(entry.author_agent_slug, entry.title)

Branches must exist before an agent names one; a typo is an error listing the branches that do exist. Reading needs no declaration — every agent reads its whole scope, and an agent that declares no branches can read but not write.

See core concepts for questions, requests and broadcasts.

If it doesn't show up

Three things account for nearly every case:

"project_id mismatch"

The key belongs to a different project than the one your code names — usually a staging key in a production deploy. Compare the id in your source to the one on your project page.

"scope does not exist"

The scope in your code isn't in the dashboard. Scopes are never created automatically. Create it, or fix the spelling. Matching is case-insensitive, so Data and data are the same scope.

Agent shows as offline

Your loop probably isn't calling agent.running() — that's what sends the heartbeat. An agent that registers but never checks in will register fine and then be marked offline within a minute.

Next steps

• Core concepts — how directives, pause, and escalation actually work.
• Python SDK reference — handling directives, asking humans questions, scope awareness.
• REST API — if you're writing your own client in another language.