Major

How to Build a Claude Agent: Tools, State, and Workflows

Learn how to build a Claude agent that turns repeatable reasoning, tool calls, and multi-step workflows into a dependable app with state, guardrails, and governed access.

Jose GironUpdated
Major and Anthropic logos side by side for building a Claude agent with tools and state

To build a Claude agent, give Claude one narrow job, a small set of typed tools, and a loop that calls the Messages API until it returns a final answer. Your code runs every tool call, stores state outside the conversation, and gates every write behind a permission or approval. Claude supplies judgment. Everything else belongs in software.

On Major, that software is built for you. The agent works out the repeatable steps of the job once, builds them into a deterministic app with its own database and logs, and runs the app from then on. You get the loop, the state, and the governance without hand-assembling each piece. The rest of this guide covers the mechanics, then the Major build.

What a Claude agent is

A Claude agent is a program with one defined job, a tools array, and a loop. Claude decides which tool to call and when the work is finished. The application does the rest: it executes calls, remembers results, and enforces limits.

Some jobs should never become agents. If the steps are fixed and the inputs are structured, write ordinary code. Reach for Claude when a step means reading unstructured input and making a call a rule cannot encode, like deciding whether a diff touches authentication logic.

Choose one job and define completion

Narrow agents finish. General ones wander. "Triage every new pull request and post a review summary to Slack" is a job. "Help the engineering team" is a wish.

Write down what done means before you write a prompt. For PR triage, done means a findings record exists, a Slack message went out, and nothing was written to GitHub without approval. That definition becomes your system prompt and your test cases.

Define a small typed tool surface

Every tool is a function your code runs when Claude asks. Anthropic's tool-use docs define three parts: a name, a description Claude reads to decide when to call it, and an input_schema in JSON Schema. Claude picks tools by description, so five precise tools beat twenty overlapping ones.

A good read tool looks like get_pr_diff(repo, pr_number) with a description that says it is read-only and must be called before any review finding. Set strict: true so Claude's calls match your schema exactly. Keep read tools and write tools separate, and name write tools so the risk is visible. request_merge_approval tells a reviewer far more than update_pr.

Implement the Messages API tool loop

Every Claude agent reduces to the same four steps.

  1. Send a request with the system prompt, the tools array, and the conversation so far.
  2. Read stop_reason. If it is tool_use, the response holds one or more tool_use blocks, each with an id, a name, and an input.
  3. Run each call and build one tool_result block per call, matched by tool_use_id. Mark failures with is_error: true and a short explanation.
  4. Append Claude's response as an assistant message and your results as the next user message, then send again. Stop when stop_reason is end_turn.

Two details break naive loops. Claude can request several tools in one response. Run independent reads concurrently and side-effecting calls in order, then return every tool_result together in the next user message. The API rejects requests where a tool_use id has no matching result, so return a result even for calls you skipped.

Non-success stop reasons need their own branches. max_tokens means output was cut off and an incomplete tool_use block should be retried with a higher limit. pause_turn means a server-tool loop hit its iteration cap, and you resume by sending the assistant content back. refusal arrives as an HTTP 200 with stop_details naming the policy category. A loop that only checks for tool_use will log a refusal as a finished job. Cap total iterations too.

Persist state outside the context window

The messages array is Claude's memory for one run. When the process ends, it is gone. Replaying yesterday's transcript into today's prompt costs more every day and still loses detail.

Keep four kinds of state, each in its own place.

  • Transcript: the messages array in memory. Use it for reasoning inside one run, then summarize or discard.
  • Database: findings, statuses, and which PRs are done. The next run queries it.
  • Files: diffs, test logs, and reports too large for a row, in object storage.
  • Audit log: an append-only table of every tool call, its input and result, and who approved it.

Give Claude a read tool such as get_prior_findings instead of replaying history. The next run starts with a query.

Connect Claude to Slack, Notion, Gmail, and GitHub

The Anthropic connector authenticates with an API key and exposes a chat action, with no triggers of its own. Events come from elsewhere: a GitHub pull request webhook, a new Gmail message, or a Slack slash command. Output goes to Slack for notifications and approvals, Notion for decision records, and Gmail for external replies. Each connector becomes a tool with its own credential, scoped to the minimum the job needs.

Add approvals, permissions, retries, and logs

The approval gate is where an agent earns trust. A tool that writes to a system of record should never execute directly. It creates a pending request, posts it to Slack with approve and reject buttons, and returns a tool_result telling Claude the action is waiting on a person. The write runs only after someone clicks approve, and the click is logged with their identity.

Permissions belong in credentials. "Do not merge" in a prompt is a suggestion to a model. A GitHub token without merge scope is a fact. Retries belong in tool code with backoff and idempotency keys, so a retried Slack post does not land twice.

Build the PR triage agent on Major

Here is the code-review agent as a Major build. A new GitHub pull request starts a workflow, Claude reads the diff and CI output, and an app records and routes the result.

  • Connectors: GitHub for diffs and comments, Slack for the summary and approval request, Notion for decision records, Anthropic for the model call.
  • The app that holds state: a managed database with a findings table, a pr_reviews table keyed by PR number, and an audit log, plus a reviewer view in the browser. Re-runs on the same PR read prior findings instead of starting cold.
  • The agent and its judgment: Claude decides which findings matter, such as a missing null check in a payment handler or a test that asserts nothing, and whether a finding is serious enough to block.
  • The deterministic part: on early runs Claude works out that every PR gets the same checks. Migrations need a down step. New endpoints need auth middleware. Changed modules need tests. The agent builds those checks into the app, which runs them the same way on every PR.
  • The trigger: a GitHub pull request workflow trigger, with the Slack approval step as a human-in-the-loop node before anything is written back.
  • Governance: GitHub, Slack, Notion, and Anthropic credentials are scoped to read plus comment, and merge stays with a human. SSO, role-based access, and the audit log apply from the first deploy.

This is where the cost structure changes. Re-deriving a checklist on every pull request is how agent spend climbs with usage. Once the app carries the repeatable checks, token spend is front-loaded while the agent figures the job out, then flattens, because the model only handles the judgment calls. Reason once. Run forever.

Hand-building the loop, database, approval flow, and audit table is reasonable for one prototype. The maintenance burden shows up when each agent has its own credential handling and a partial log table. Major is the enterprise platform where agents build the software they run on, so every app an agent builds is stateful and governed from the start, and the next team can run it too.

PR triage is a good first build because the job is narrow, the checklist repeats, and the approval point is obvious.

What this guide does not cover

This guide covers a tool-using application agent with application-managed state and approvals. It does not specify a production deployment model, a model evaluation suite, a latency budget, or a universal choice of Claude model. Test those against your data, privacy requirements, and failure modes before launch.

More use cases by tool: More GitHub use cases, More Gmail use cases, More Notion use cases, More Slack use cases.

Start building on Major

Build your Claude PR triage agent on Major: connect GitHub, Slack, and Anthropic, let the agent turn the repeatable review checks into an app with its own database and audit log, and keep merge approval with your reviewers.

Related articles

Frequently asked questions

What is a Claude agent?
A Claude agent is Claude plus four things your application provides: typed tools it can call, a loop that keeps sending requests until the job is finished, state stored outside the conversation, and a policy for what it may do. Claude handles the judgment. Your code runs each tool, keeps records, and enforces permissions and approvals.
How does Claude use tools?
You send a Messages API request that includes tool definitions. When Claude wants a tool, the response has stop_reason tool_use and one or more tool_use blocks. Your code runs each call and sends back matching tool_result blocks in the next user message. Claude continues from there until it returns end_turn with a final answer.
Can Claude remember across sessions?
Not by itself. The messages array only lasts for one run. To remember across sessions, your application stores findings, statuses, and files in a database or object storage, then gives Claude a read tool to query them at the start of the next run. That is cheaper and more reliable than replaying old transcripts.
How do you secure a Claude agent?
Give each tool its own credential scoped to the minimum the job needs, such as read plus comment on GitHub with no merge rights. Keep secrets out of prompts. Route every write to a system of record through a human approval step, and log each tool call with its input, result, and approver in an append-only audit table.