Build an Agent

Pre-requisite: please read Agents & Tools user guide first to understand how agents and tools work from a user perspective.

You will learn how to build a couple of simple agents in a few lines of code.

Creating a haiku agent

Let's start by creating a simple agent to show the high-level structure of an agent. Copy the following code into a file like haiku_agent.py:

haiku_agent.py

import dyad


def haiku_agent_handler(
    context: dyad.AgentContext,
):
    yield from context.stream_to_content(
        system_prompt="You must respond with a haiku",
    )

Then, start Dyad with the following command:

dyad --extension=./haiku_agent.py

If you type in: "@" in the chat input, you should see "@haiku" as one of the chat suggestions. Then, type in a prompt like "tell me a joke" and see what you get back.

Tip: If you hit an error, make sure that the path to the extension module is correct.

Let's explain this code example step-by-step:

1. import dyad should always be used instead of importing from specific sub-modules (e.g. import dyad.foo) because it's the only public API which will be stable over releases.
2. @dyad.agent(name="haiku") is a function decorator which makes a function into an agent. The name argument is what is shown in the chat suggestion.
3. The function parameter context is of the type dyad.AgentContext this contains the user input and state and represents essentially the interaction with an agent.
4. yield from context.stream_to_content is a method on AgentContext which allows you to call an LLM and incrementally update the UI.

Creating a tools agent

Oftentimes, you will want to create an agent which can call various tools. You can write a tool-calling agent in just a dozen lines.

Here's an example of a simple agent that selects between multiple tools:

Greetings agent

from collections.abc import Generator

import dyad


def hello_world_agent(
    context: dyad.AgentContext,
) -> Generator[None, None, None]:
    while True:
        step = yield from context.stream_step(
            tools=[formal_greeting, casual_greeting]
        )
        if step.type == "error":
            return
        if step.type == "tool_call":
            # only 1 tool call and then done
            return
        if step.type == "default":
            yield from context.stream_to_content()
            # Finish
            return


@dyad.tool(description="Creates a formal greeting")
def formal_greeting(
    context: dyad.AgentContext,
    output: dyad.Content,
    *,
    name: str,
):
    """Creates a polite, formal greeting. Use very formal english if the user sounds formal."""
    greeting = f"Dear {name}, I hope this message finds you well."
    for chunk in context.stream_chunks(
        input="Create a formal greeting based on this input... " + greeting,
    ):
        output.append_chunk(chunk)
        yield
    return greeting


@dyad.tool(description="Creates a casual greeting")
def casual_greeting(
    context: dyad.AgentContext,
    output: dyad.Content,
    *,
    name: str,
):
    """Creates a friendly, casual greeting.

    Use this if the user sounds like they want a casual chat."""
    greeting = f"Hey {name}! 👋"

    for chunk in context.stream_chunks(
        input="Create a casual greeting based on this input... " + greeting,
    ):
        output.append_chunk(chunk)
        yield

    return greeting

And that's it! In a few lines, you created your own agent assembled with multiple tools.

Next steps

Next, let's learn how to build a new tool:

Build a tool