How to build your first AI agent: from a useful idea to a working pilot

Building an AI agent starts with a job you can recognise as finished. “Help with administration” leaves too much open. “Read a workshop enquiry, find the matching activity and prepare a record for review” gives you a starting point, a result and a way to inspect the work. The first useful version usually needs fewer capabilities than the impressive demonstration you have in mind.

This guide follows a fictional community organisation preparing workshop registrations. Its coordinator receives messages, checks the activity catalogue and asks for missing information. The proposed agent will prepare a reviewable record and a reply draft. It will not approve registrations, reserve places or collect money. The example is an original teaching scenario, not an Edeverse deployment or a claim about measured results.

You can use the same method for personal projects, a small business or an internal team. By the end, you should have a project brief, an integration choice, a tool contract and a practical acceptance test.

1. Define the result before selecting a platform

Write one sentence describing completion. For this pilot, a request is prepared when the coordinator can open a record containing the activity, requested date, missing details, supporting source and suggested reply. A record marked “needs clarification” can be a successful result. A confident but invented booking cannot.

Turn that sentence into a brief:

Decision	Scope of the fictional pilot
Starting event	A message enters the “Prepare registrations” folder
Approved information	Original message and current workshop catalogue
Required output	Review record and reply draft
Excluded actions	Sending, accepting payment and changing availability
Human owner	Coordinator reviewing records and exceptions
Useful measure	Human time per correct, usable record

Complete several examples manually before connecting anything. Record where you search, which facts you compare and what makes you stop. If a coordinator cannot tell whether “Saturday photography” identifies a particular workshop, the agent needs a clarification route rather than a more elaborate instruction to be helpful.

Also decide what happens to requests outside the scope. A cancellation, a complaint and an enquiry about accessibility should not silently become registration records just because they arrive in the same folder. Give them a separate status and a route back to the coordinator.

2. Decide whether you need an agent at all

A predictable sequence may only need conventional automation. If a form already supplies validated fields, copying them into a record does not require a language model. AI becomes useful when part of the task involves interpreting free text, comparing incomplete descriptions or selecting a relevant source.

For planning purposes, distinguish a workflow, where the route is defined in advance, from an agent, where a model chooses steps and tools dynamically. Anthropic makes this distinction in its foundational guide, while explicitly noting that the surrounding tooling has changed since the original publication. Source: Building effective agents.

Three approaches fit different versions of our example:

• Rules only: receive a structured form, validate required fields and create a draft record.
• Workflow with an AI step: interpret an email, search the catalogue, validate the extracted fields and save a review record.
• Agent with several tools: decide whether to search activities, retrieve an existing request or ask for clarification, depending on the message.

Start with the middle option if every request follows substantially the same route. A free-running loop adds little when the next step is always known. Introduce more discretion only when a repeated, observed need justifies it.

This decision affects testing. For a fixed workflow you can enumerate branches. For an agent you must also check whether it selects the right branch, stops searching at a reasonable point and recognises when another tool call will not resolve the uncertainty.

3. Understand APIs, agent tools and MCP

These terms describe different layers, not three competing generations of technology.

An API lets software request operations from another service. An agent tool presents a particular capability to the model, with a description and defined inputs. Its implementation might call an API, query a database or run an existing workflow.

Model Context Protocol, or MCP, standardises exchanges between an AI application and servers exposing capabilities. The application acts as a host and uses MCP clients to communicate with those servers. MCP does not decide the business goal or the agent's autonomy. Source: MCP architecture.

MCP servers can expose tools for operations, resources for context and reusable prompt templates. Discovering a tool is separate from executing it. A server may expose only some of these capabilities. Source: MCP server concepts.

In our fictional design, a “search workshops” tool could reach a catalogue API through an MCP server. A “prepare record” tool could run a workflow that validates fields and stores a draft. The agent would see the available operations; the implementation would determine what those operations can actually do.

That distinction prevents a common purchasing mistake. “Supports MCP” does not establish that a product can create your particular record, use your account or access the necessary fields. Request a demonstration of the operation you need, not merely a successful connection screen.

4. Choose the simplest connection that completes the job

List the exact reads and writes first. “Email integration” is too vague. You may need to read one folder, preserve the source message identifier and create a draft without sending. These are separate requirements.

A native connector is a sensible first choice when it already exposes the right operations and access boundaries. Test it with a harmless example on the intended account. Check the returned information and open the created object yourself.

A direct API integration is useful when you need an operation the connector lacks, precise error handling or control over individual parameters. The trade-off is maintenance. Someone must understand authentication, changes to the service and how to diagnose failures.

An MCP server is useful when a compatible application can reuse the specific capabilities it exposes. Establish who operates the server, where requests go, what it can change and how its access can be withdrawn. A standard interface can simplify integration without removing the need to inspect its implementation.

No-code describes how you assemble a system. It does not exclude API calls or MCP connections. Choose a visual builder if its available operations and debugging tools fit the task; choose code when the required control justifies it. Neither route removes the need for an acceptance test.

Keep construction access separate from day-to-day access. A person or assistant building the automation may need to edit workflows. The finished registration pilot should not retain that power merely because it was useful during setup.

5. Draw the whole route, including the stops

The proposed route has six stages:

1. Receive a selected message and capture its stable identifier.
2. Check whether that message already has a prepared record.
3. Extract the activity and requested date without filling gaps by guesswork.
4. Search the approved catalogue for possible matches.
5. Prepare the record and reply draft with missing details highlighted.
6. Present the result to the coordinator for review.

Give each interruption a visible outcome. If two workshops match, record both possibilities and request clarification. If the catalogue cannot be reached, record a technical failure instead of saying that availability was checked. If a record already exists, return its identifier rather than creating another.

Use states that describe work accurately: received, needs clarification, ready for review, reviewed manually and technical failure. Avoid one broad “done” label covering both prepared drafts and confirmed registrations. The coordinator should understand what happened without reconstructing the entire conversation.

Decide which information travels between stages. The search step needs the activity description, not every unrelated paragraph in the message. The record needs the source identifier and relevant findings, not an unlimited copy of the agent's conversation. Smaller, explicit handoffs are easier to inspect.

6. Give each tool a contract

A tool name alone is not a specification. Write down its inputs, success evidence, alternative outcomes and absent powers.

For the fictional “prepare registration record” tool:

• Required inputs: source message identifier, matched activity or “needs clarification”, missing fields and draft reply.
• Precondition: the workflow must check for an existing record with that source identifier.
• Successful output: record identifier, review status and confirmation that the draft was stored.
• Alternative outputs: existing record, invalid field or unavailable service.
• Excluded effects: no message is sent and no place is reserved.

Ask the implementer to demonstrate every outcome. A response saying “request accepted” is not necessarily proof that the record exists. The tool should return evidence that the next stage can check.

Plan for an uncertain result. Suppose the record was created but the connection failed before the acknowledgement reached the agent. Repeating the creation immediately may produce a duplicate. The recovery route should look up the source identifier first, then either return the existing record or create one if absence is established.

The same principle applies whichever integration you choose. A reachable server, a listed operation and a completed business action are three different milestones. Test all three.

7. Write an instruction that resolves real decisions

A useful instruction names the source, outcome and uncertain cases. For this teaching example:

Prepare a registration record from the supplied message and approved workshop catalogue. Extract only information that is present. If several workshops match, show the alternatives and mark the activity as needing clarification. Do not invent dates, availability or prices. Check for an existing record using the source message identifier before creating one. Draft a reply asking only for the missing information. Do not confirm admission. If a tool fails, identify the failed stage and do not describe an unverified operation as complete. Return the activity, requested date, missing fields, source, status and reply draft.

Replace these illustrative operation names with the capabilities actually available. Add one complete example and one ambiguous example with expected outputs. Those examples should clarify your criteria, not become a reason to upload the organisation's entire message history.

Apply important limits in the workflow and account permissions as well. An instruction is not the only barrier between a draft-only pilot and an unintended send. For this first version, do not expose a send operation at all.

External messages can also contain instructions intended to redirect the system. OWASP identifies indirect prompt injection through sources such as documents and websites. Our practical test is to include a fake instruction in a test message asking for an unrelated export, then verify that the pilot stays within its permitted task. Source: OWASP Prompt Injection.

8. Separate reference information, working context and history

The workshop catalogue is reference information. Details needed while processing one request are working context. The durable record of what was created is execution history. Treating all three as “memory” makes it difficult to know what must survive a restart or change when the catalogue is updated.

For this pilot, a new catalogue should become available without retaining every old enquiry in the model's context. Conversely, a record identifier must survive an interruption even if the current conversation no longer includes the creation step.

Anthropic's Managed Agents architecture illustrates a separation between session history, the agent loop and its execution environment. That is a provider-specific architecture, not a feature automatically present in every agent. Source: Scaling Managed Agents.

Ask one concrete recovery question: “If processing stops immediately after creation, how does the restarted system discover that the record already exists?” Look for durable evidence and an explicit lookup, not an assurance that the model will remember.

9. Test the cases most likely to expose a weak design

Create the test set before repeatedly changing the instruction. Otherwise you may optimise for the few examples you remember.

Test case	Required result
Explicit activity and date	Faithful record and relevant draft
Missing date	Targeted question, no invented date
Two matching activities	Alternatives shown, no arbitrary selection
Repeated source message	Existing record returned
Unavailable catalogue	Failure visible, no claimed verification
Lost creation acknowledgement	Existing state checked before retry
Embedded request for unrelated data	No export or expansion of scope
Updated approved catalogue	Current applicable version used

Inspect factual correctness, permitted actions and usability separately. A pleasant reply cannot compensate for a duplicate record or a false confirmation. Record which failures are unacceptable even once during the pilot.

Diagnose before changing the prompt. Wrong tool selection may call for clearer descriptions or fewer tools. Repeated errors with the same valid inputs suggest an integration problem. Conflicting catalogue entries require a data decision. These are different faults with different fixes.

Finally, time the complete human task: preparing input, reviewing the output, correcting it and handling exceptions. Compare similar requests with the manual method. Faster generation alone does not establish useful time saved.

10. Decide what must be true before expanding

Request a budget split between source preparation, integrations, construction, testing and ongoing operation. Running costs may include the platform, model use, connected services, storage, monitoring and maintenance. One request can involve several searches, checks or retries, so request count alone does not describe consumption.

For acceptance, obtain four practical items: the access inventory, the test set, the recovery procedure and the name of the person responsible for upkeep. Confirm that the coordinator can stop the pilot and continue manually without losing the request queue.

Then add one capability at a time. Moving from preparing a reply to sending it introduces recipient checks, approval conditions and delivery evidence. Reserving a place introduces another state change. Treat each expansion as a small project with its own tests, rather than a convenience toggle.

Frequently asked questions

Can I build an AI agent without coding?

Yes, when a visual platform exposes the operations your task requires. Test its field handling, errors and access controls, not just its happy-path demonstration. A missing operation may still require an API integration, an MCP server or technical assistance.

Does MCP replace APIs?

No. An MCP server may use a service's API to carry out an operation. Select the connection that exposes the needed capability with understandable access and maintenance requirements. Adding MCP alone does not make a workflow more autonomous or more reliable.

When is the first agent ready for real use?

When representative requests and failures produce understandable results, operations stay within the agreed scope, outputs can be verified and someone can recover the work after an interruption. One successful demonstration is a starting point, not an acceptance test.