Skip to main content

Agent Workflow

The recommended pattern for agents using OpRelay as their coordination layer.

Session lifecycle​

Session start:
  1. get_context(project_key) → load current state
  2. Use facts/decisions to inform your work

During work:
  3. upsert_fact() for operational state worth remembering
  4. upsert_decision() for engineering decisions made

Session end:
  5. record_run() → log what you did

Coordination (multi-agent)​

When multiple agents work on the same project, OpRelay provides deterministic task coordination:

1. Create tasks​

{
  "name": "core_create_task",
  "arguments": {
    "project_key": "my-project",
    "title": "Implement OAuth2 flow",
    "priority": "high",
    "auth_token": "TOKEN"
  }
}

2. Claim tasks​

Advisory-lock-based claiming prevents two agents from working on the same task:

{
  "name": "core_claim_task",
  "arguments": {
    "task_id": "uuid-here",
    "agent_id": "my-agent-id",
    "auth_token": "TOKEN"
  }
}

3. Transition tasks​

Append status transitions as work progresses:

pending → in_progress → done
                      → failed
                      → blocked

4. Record outcomes​

Always record what happened — success or failure:

{
  "name": "record_run",
  "arguments": {
    "project_key": "my-project",
    "agent": "claude-code",
    "summary": "Implemented OAuth2 flow with PKCE",
    "meta_json": {
      "status": "success",
      "files_touched": ["server/src/auth.ts", "server/src/routes/oauth.ts"]
    },
    "auth_token": "TOKEN"
  }
}

Facts as coordination state​

Use facts to communicate operational state between agents:

{
  "name": "upsert_fact",
  "arguments": {
    "project_key": "my-project",
    "category": "deploy",
    "key": "last_successful_deploy",
    "value_json": "{\"sha\": \"abc1234\", \"env\": \"staging\", \"time\": \"2025-01-15T10:00:00Z\"}",
    "auth_token": "TOKEN"
  }
}

Other agents reading get_context will see this fact and can make informed decisions.