Wyrd docs v0.4.1 Use with your coding agent Reference GitHub

Build and verify / Author in code

Author in code

Build your Cards in code instead of YAML files. One program defines a Service, the Agent it runs, and a Verifier bound to that Agent, declares them, verifies a passing and a failing answer, and records each answer in the Service’s table.

You need the server and the quickstart directory from Set up Wyrd. Run everything below there.

1. Write the program

The Python program uses Pydantic models. Add them with the pydantic extra:

bash
uv add "wyrd-ai[pydantic]==0.4.1"

Without Pydantic, map each input slot to its own schema, inputs={"answer": {"type": "string"}}. Table takes the row’s whole object schema, and write takes a dictionary row.

author.py python
"""Author a Service, its Agent, and its Verifier in code, declare them, verify
two answers, and record each answer in the Service's table."""

from pydantic import BaseModel
from wyrd import WyrdState
from wyrd.verify import (
    Agent,
    Check,
    ComparisonOperator,
    Component,
    ExecutionRoute,
    Prompt,
    Requirement,
    Service,
    Table,
    Verifier,
)


# The Verifier's evidence: one slot per field.
class Inputs(BaseModel):
    answer: str


# A row of the Service's table: one column per field, in order.
class Reply(BaseModel):
    answer: str
    verdict: str


# The Verifier: one requirement over the evidence slot named `answer`.
no_refund_guarantee = Verifier(
    "no-refund-guarantee",
    inputs=Inputs,
    requirements=[
        Requirement(
            "no-refund-guarantee",
            "The answer never promises a guaranteed refund.",
            Check.assert_("inputs.answer", ComparisonOperator.NotContains, "guaranteed refund"),
        )
    ],
)

# The component: an Agent and the Prompt it runs.
refund_agent = Agent(
    "refund-agent",
    prompt=Prompt.openai_chat("gpt-4o", messages="Answer the refund question: {{question}}"),
    execution_route=ExecutionRoute.wyrd_gateway(deployment="openai"),
)

# The Service: the Agent under the alias `agent`, verified by the Verifier,
# and a table for the answers it gives.
service = Service(
    "refund-replies",
    tables=[Table("refund_replies", Reply)],
    components=[Component("agent", refund_agent, verified_by=[no_refund_guarantee])],
)

# No Card names a version: declaration selects each one and returns them.
state = WyrdState.declare(service)
print(f"service: {state.root_ref}")
print(f"agent:   {state.card_ref('agent')}")

state.start_bifrost()  # the writer; the one declared table is active
try:
    for answer in ("Your refund request is approved.", "You have a guaranteed refund."):
        # A Run whose view is the Agent, where the Verifier is bound.
        with state.run("agent") as run:
            result = run.observe.verify("no-refund-guarantee", answer=answer)
            # Buffered, not yet stored: shutdown() drains it.
            run.bifrost.write(Reply(answer=answer, verdict=str(result.verdict)))
        print(f"{result.verdict}: {answer}")
finally:
    state.shutdown()

Every definition takes a name and no version. The Prompt goes directly into the Agent and registers with it. inputs names the Verifier’s evidence slot, answer, and verify supplies the evidence under that name.

The component alias, agent, is how the program selects the Agent at runtime. The Verifier is bound to that component, so the program verifies on the Agent’s view: state.run("agent"). Table declares bifrost.datasets.refund_replies with one column per schema property, in order, and declaration creates it.

The program supplies the answers itself and never calls the Agent’s model, so it needs no gateway deployment.

2. Run it

bash
uv run author.py

Every language prints the same:

text
service: Service/refund-replies@0.1.0#<uid>
agent:   Agent/refund-agent@0.1.0#<uid>
passed: Your refund request is approved.
failed: You have a guaranteed refund.

The server selected each version at declaration, and the state declare returns holds the registered Cards at those exact versions. Your definitions stay unversioned; they are what you declared, not what the registry stored. To use Cards that are already declared, load them with WyrdState.from_path or reference them by exact CardRef.

The failed verdict is a result, not an error: the check ran, and the answer promises a guaranteed refund.

Run the program again. Nothing changed, so it prints the same versions and uid values.

3. Read back the rows

run.bifrost.write writes the Service’s one declared table, so it names none. It queues the row and returns before it is stored. shutdown sends everything still queued, so a program that exits without it can lose rows.

Save this query as replies.sql:

replies.sql sql
SELECT answer, verdict, subject_card_uid, run_id FROM bifrost.datasets.refund_replies ORDER BY wyrd_ingested_at DESC LIMIT 10

Run it against the address wyrd init printed, with wyrd run as in setup:

bash
wyrd query --server http://127.0.0.1:8080 --file replies.sql

It prints one JSON row per answer, newest first:

text
{"answer":"You have a guaranteed refund.","verdict":"failed","subject_card_uid":"<uid>","run_id":"<run_id>"}
{"answer":"Your refund request is approved.","verdict":"passed","subject_card_uid":"<uid>","run_id":"<run_id>"}

subject_card_uid is the uid the agent: line printed, and each answer has its own run_id. Rows become queryable shortly after the program ends: if one is missing, repeat the query for up to a minute.

4. Change the Verifier

In the program, change the checked text from "guaranteed refund" to "guaranteed" and run it again. The service: line shows a new version, and the agent: line is unchanged.

The Service binds the Verifier, so its content changed too: declaration gave the Verifier and the Service new versions. Verdicts from earlier runs still name the versions they checked.

Choose a version yourself

Pass a version to a constructor to set it, as metadata.version does in YAML. Cards and versions explains how chosen and selected versions behave.

5. Use Pydantic models (Python)

In Python, a Pydantic model class can be a slot’s schema, and an instance of it is that slot’s evidence. This Service has two components, each with its own Agent and Verifier, in separate modules. Its Agent checks call a model, so running it needs an openai deployment in the LLM gateway.

In quickstart, create a service directory and save these five files in it, at the paths their tabs show:

components/report_writer/agent.py python
"""The report-writing component's definition."""

from wyrd.verify import Agent, ExecutionRoute, Prompt

agent = Agent(
    "report-writer",
    prompt=Prompt.openai_chat(
        "gpt-4o",
        messages="Write a customer report using only these source facts: {{source}}.",
    ),
    execution_route=ExecutionRoute.wyrd_gateway(deployment="openai"),
)
  • inputs={"report": Report} maps a slot to its model. inputs=Inputs passes one model whose fields are the slots.
  • ResponseFormat.verdict() asks the judge for the standard verdict. verdict(data=JudgeData) adds a typed data field to it; data also takes a JSON Schema object, so Pydantic is optional.
  • Importing a module only builds definitions. Nothing registers or runs until main.py calls WyrdState.declare.

From service, run:

bash
uv run main.py
text
Report quality: passed
Release controls: passed

ComparisonOperator and ExecutionRoute are typed forms of the YAML values, and AgentRunConfig, also from wyrd.verify, sets an Agent’s run limits through run_config:

finance_release.py python
# `policy-judge`: a model that reads the policy with `fs.read` and returns a
# verdict on the release.
policy_judge = Agent(
    "policy-judge",
    prompt=Prompt.openai_chat(
        "gpt-4o",
        messages=(
            "Read /inputs/policy.json with fs.read. Decide whether this release "
            "follows the company sharing policy, citing the report and the policy. "
            "Report: {{report}} Recipient: {{recipient}}"
        ),
        response_format=ResponseFormat.verdict(),
    ),
    execution_route=ExecutionRoute.wyrd_gateway(deployment="openai"),
    tool_names=["fs.read"],
    run_config=AgentRunConfig(max_iterations=3),
)

The Verifier reference lists every operator and field.

If it fails

You seeFix
WYRD_SDK_404_UNKNOWN_VERIFIERVerify on the view the Verifier is bound to: state.run("agent")
WYRD_SDK_400_BIFROST_NOT_STARTEDCall start_bifrost before the first write
WYRD_VALA_409_BIFROST_FINGERPRINT_MISMATCHThe table exists with different columns: keep its schema, or use a new table name
No rows after a minuteCheck that the program reached shutdown without an error

Next

Bindings covers where else a Verifier can attach and who runs it. Runs and observations wraps real requests in Runs.

Last updated