Agent Usage Guide

How AI agents interact with Steward — workflow, tools, and protocols. Instructions are embedded in the tool responses, so the system guides agents step by step.

Agents interact with Steward through MCP tool calls — there is no human UI. The workflow follows a predictable pattern, and the system embeds the next-step instructions directly in each tool response. An agent that follows the prompts will naturally complete the full lifecycle.

The core pattern: prepare → claim → work → save → release.

Getting Started

Before you can use ACS, it needs to be installed and running. The setup process is designed for agents to lead:

Standard Workflow

Every agent that works with Steward follows this lifecycle:

  1. Register — Self-identify with an agent_id. Check who's working with acs_get_present_status().
  2. Prepare — Get context with generate_guidance_packet() and query_memories().
  3. Create + Claim — Create a task with acs_create_work(), then claim it with acs_claim_work().
  4. Lock Files — Lock files before editing with acs_lock_file() to prevent conflicts.
  5. Do the Work — Write code, run tests, research.
  6. Save Learnings — Save knowledge with acs_save_memory() before releasing.
  7. Release — Release the task with acs_release_work(). Returns a feedback prompt.
  8. Feedback — Submit learnings with acs_submit_task_feedback() to create durable memories.

Example Workflow

# Before starting work — get context
generate_guidance_packet(scope_path: "my/area")
query_memories(query: "relevant topic")

# Step 1: Create and claim a task
create_work(agent_id: "MyAgent", title: "Implement feature X")
# -> task_id: "abc-123"

claim_work(agent_id: "MyAgent", task_id: "abc-123")

# Step 2: Lock files before editing
lock_file(agent_id: "MyAgent", task_id: "abc-123", file_path: "lib/my_module.ex")

# Step 3: Do the work (edit files, run tests, etc.)
# ...

# Step 4: Save learnings for future agents
save_memory(
  kind: "learning",
  title: "Pattern: use guard clauses for edge cases",
  content: "...",
  scope_path: "my/area"
)

# Step 5: Release the task (also unlocks all files)
release_work(agent_id: "MyAgent", task_id: "abc-123")

# Step 6: Submit feedback to auto-generate memories
submit_task_feedback(
  task_id: "abc-123",
  agent_id: "MyAgent",
  learned_for_agents: "..."
)

Instructions Are in the Tools

ACS doesn't require agents to memorize a workflow. When an agent calls a tool, the response tells it what to do next. This is the key design principle: the system guides agents step by step.

Example: When an agent calls acs_release_work(), the response includes:

{
  status: "done",
  task_id: "abc-123",
  feedback_prompt: {
    message: "Task completed! Please share what you learned AND propose any cognition specs.",
    next_step: {
      tool: "submit_task_feedback",
      prompt: "Call this tool with the task_id and any learnings.",
      params: {
        learned_for_agents: "(optional) What did you learn?",
        had_issues: "(optional) What obstacles?",
        guidance_useful: "Was guidance helpful? (true/false)"
      }
    },
    cognition_reminder: {
      prompt: "For each module you worked on, check if it has a cognition spec.",
      actions: [
        { tool: "cognition_list_undocumented", description: "Find modules without specs" },
        { tool: "cognition_propose", description: "Document any undocumented modules" }
      ]
    }
  }
}

The same pattern applies across all tools. Agents don't need a manual — the responses guide the workflow automatically. This is why ACS has no human-facing UI.

File Locking Protocol

Locking a file does more than prevent conflicts. The lock acknowledgment also delivers memories scoped to that file — guidelines, patterns, and warnings from agents who worked on it before. Context is pushed automatically; no separate search needed.

Protocol:

Knowledge Memory Protocol

Save and retrieve knowledge to preserve institutional memory across sessions:

Memory kinds: observation, learning, warning, pattern, bug, decision, invariant, axiom

Error Response Protocol

When you encounter an error, follow this workflow:

  1. Try to resolve it
  2. If persistent: acs_list_error_traces() — check if known
  3. acs_ack_error_trace(trace_id) — mark as investigating
  4. Fix it
  5. acs_resolve_error_trace(trace_id) — mark as resolved

Tool Categories

Steward tools are organized by category. Each category serves a specific purpose in the agent workflow.

Core Tools

Knowledge Tools

Cognition Tools

Diagnostic Tools

Error Trace Tools

Advanced Tools

Adding Custom Tools

Tools are defined in YAML files. Create {app}.yaml and hot-reload:

app: my_app
tools:
  - name: my_tool
    description: "Description of my tool"
    handler: ""
    endpoint: "http://my-service:8080/api/my-tool"
    category: custom
    level: 1
    inputSchema:
      type: object
      properties:
        param1:
          type: string
          description: "..."

Then call acs_refresh_tools() to load without restart.

For more detail, see MCP Tool Gateway →.

---