I Built My First Real AI Agent Today. Here Is What I Learned.

A first-hand account of building a real agent on platform.claude.com. OAuth friction, YAML gotchas, and what shifted once it actually ran.

A first agent is mostly a mental model you build by reading the diagram while you draw it.

I have spent the last six months telling clients what an AI agent does. I could describe scoring rules, conditional logic, decision transparency, and the difference between a routine and an agent. What I had not done, until today, was build one that actually runs in production. There is a real gap between explaining something and shipping it, and I felt that gap for most of the day.

The agent I built is a Daily Operations Agent. It lives on platform.claude.com, runs in the cloud, has access to my Gmail through OAuth, and produces a ranked summary of the things in my inbox that actually need attention. The morning run finished a few hours ago. By the time it did, my mental model of what an agent is had moved from a description to something closer to a working blueprint.

This is the story of building it. The specific friction. The specific surprises. The lessons that only land when you have done the thing.

Where the agent actually lives

The first reframe came before I wrote any YAML. I have been working with Claude Code for months, which runs on my Mac and reads local files. A production agent does not run there. It lives on platform.claude.com, the cloud environment for agents that operate independently, on a schedule, and against external services.

That difference sounds small. It is not, once you start building. A Claude Code skill can read the markdown file sitting on my desktop. A platform agent cannot. The instinct to point at a file has to go. The agent has to receive its data through a connector or fetch it from an API at runtime. Everything that lives on my computer is invisible to it.

The agent itself is a YAML file with four parts. A name. A system prompt that holds the entire brain of the agent, including all of its scoring rules, output format, and decision logic. A list of MCP servers that it can connect to. And a list of tools, which are the specific actions it can take inside each connector.

Every session is a logged run. The platform records what the agent did, what it decided, and what it chose to skip. That last part matters more than I realized going in.

The OAuth swamp

Authorizing Gmail took longer than building the agent itself. That surprised me.

To allow the agent to read my inbox, I had to set up an OAuth application in the Google Cloud Console. OAuth is the consent flow that lets one application access data inside another. It sounds simple in description. The consent screen has about a dozen small decisions, each one of which interacts with the others, and you only know if you got them right at the end when the connection works.

The Gmail MCP API is its own thing, separate from the standard Gmail API. MCP stands for Model Context Protocol, the connector layer that enables the agent to communicate with Gmail in a structured way. You enable it inside the Google Cloud project, not the standard Gmail API.

The first decision is user data versus application data. The right answer for an agent that reads a person’s inbox is always user data. The first time through, the labels confused me, and I picked the wrong one. That cost me a few minutes.

The redirect URI is the address that Google sends the user back to after they approve the app. For an agent on the Anthropic platform, the correct value is https://claude.ai/api/mcp/auth_callback. I got this one wrong twice before reading it carefully. The second time, I had a trailing slash that should not have been there.

Apps in testing mode require you to list the test users by email. I forgot this on the first try, hit the consent screen, and was politely told I was not on the list. Publishing the app to production removed the restriction.

The final friction is a warning from Google that the app is unsafe. For a personal tool that has not been verified, this warning is normal. The fix is to click through, not to start over. I did not know that the first time, and I almost rebuilt the OAuth project from scratch before reading the error closely.

The OAuth piece is more conceptually crowded than technically hard. Three or four small decisions interact, and the feedback loop is slow. The friction lives in the consent screens, not in the YAML.

The first time, the agent decided not to do something

The conceptual moment of the day came during the second session. The agent did something that a routine cannot do, and that small difference is the entire reason the word agent is worth using as a separate term.

A routine follows a fixed script. It runs from top to bottom, every time, with no decisions involved. The Daily Operations Agent has a morning pass and an afternoon pass. The morning pass produces a ranked list of inbox items. The afternoon pass is supposed to check for changes since morning.

I ran the morning pass, then waited an hour, then triggered the afternoon pass to see what would happen. The agent compared the new state of the inbox to the morning’s output, decided that nothing meaningful had changed, and skipped. It logged the decision, explained the reasoning, and ended the session.

That is the moment the architecture clicked. A routine would have run the second pass anyway, because a routine has no concept of looking at its own previous output. An agent scores, ranks, reasons, compares, and decides whether to act. The afternoon pass runs only when something has changed, which is conditional logic, a core agent behavior.

The other thing that made it feel like an agent rather than a script was that the reasoning was visible. The session log read like a short note from a thoughtful junior employee. Nothing materially new since the 9 a.m. summary. Three minor messages came in, none on the priority list. Skipping the second pass.

Decision transparency is what makes an agent trustworthy. A black-box agent that only produces output is hard to trust because the user has no way to verify its judgment. An agent that shows its work is something you can audit, push back on, and refine.

The first time the agent chose not to run the second pass, the architecture stopped being abstract.

YAML gotchas

The agent file itself encountered a few minor problems that nobody covers in their tutorials. None of them was blocking. They were the kind of friction that costs five or ten minutes each, and the costs add up.

The first was that credential_vault_id does not go inside mcp_servers. I tried to put it there because it seemed related. The platform returned a validation error that said the field was unrecognized, which is technically true but slightly misleading. The field is recognized, just not in that scope. The credential vault gets linked at session creation time, not in the YAML.

The second was that tools do not go inside mcp_servers either. Same error. Tools is its own top-level block, and within it, each tool has an mcp_server_name field that must exactly match the name of an mcp_server defined elsewhere in the file. Small mismatches will silently break the connection.

The third was the dumbest of the day. I had a duplicate field name and accidentally wrote "url: url:" instead of "url:". The whole file failed to parse, and the error pointed to something entirely different. It took me longer than I want to admit to find that one.

The error messages on this platform are helpful, but they do not always indicate the scope of the problem. They tell you a field is unrecognized when the real story is that the field is in the wrong place. This is the kind of detail you only learn by doing it. The lesson is to read the schema reference once before you start, rather than writing the file by analogy with other YAML you have seen.

What changed by the end of the day

The biggest change is not the technical knowledge, even though that grew. I can now say I have built one. That is a meaningful difference from being able to describe one. The next time I am in a conversation about agents, with a client, or in a Medium piece, or on a podcast, the ground I am standing on will be different. The OAuth screens, the YAML validation errors, and the moment the agent decided not to run the second pass. None of that transfers when you read about it. You have to do it.

The architecture knowledge transfers directly to client work. If I am consulting with a health center on how to automate part of their outreach process, I now have a working mental model of where the agent lives, how it gets data, what kinds of decisions it can make, and how to set up the consent flow. I had pieces of that mental model from reading. The full version came from shipping.

The other shift is around trust. A scoring agent that explains its decisions is more trustworthy than one that just produces output. Today reinforced that. The reason I trust the Daily Operations Agent enough to act on its morning summary is that the session log shows the reasoning. If the ranking looks off, I can read what the agent saw and either correct the system prompt or push back on the decision. That feedback loop is what makes the thing usable.

The last lesson is about architectural choices up front. Local file access and cloud agent access are fundamentally different. If you start by writing a Claude Code skill that reads your local markdown notes, and you later try to migrate it to a platform agent, you will have to rebuild the data layer. The earlier you decide which world the agent lives in, the less rework you do later.

The next agent will be faster because the base mental model is now in place. The third will be faster than the second. The slow one is always the first one.

Thanks for reading, now go build something fun.

Eddie

P.S. If you want a smaller starting point before going full-agent, I built three Claude Code skills that I use every week. Skills are the simpler version of the same idea: your own AI tooling, built for how you actually work. The bundle is at https://e2larsen.gumroad.com/l/the-solopreneur-skills-stack.