BUILD

Build your own agent

This guide is for practitioners who need a deliberation perspective the catalog does not cover. You will define a role card, bind it to adapter ports, register it with a session, and verify it against the conformance suite. By the end, your custom agent runs inside the same deliberation loop as any catalog persona.

CAUTION

Before building a custom agent, check the catalog for a close match — adapting an existing persona's constraints is faster than writing a new role contract from scratch, and catalog agents carry pre-validated conformance records.

Prerequisites

Verdaca installed at 0.1.0 or later (pip show verdaca to verify)
A working session configuration in verdaca.yaml with at least one memory adapter and one LLM provider configured
Familiarity with the port contract for any adapter you intend to override — read the Conceptual model adapter contract section first

Agent anatomy

A Verdaca agent is three things bound together: a role card that defines what the persona argues and under what constraints, an adapter list that specifies which port implementations it may call, and a conformance record that certifies it passes the no-waiver test suite. All three must be present before the kernel will accept the agent into a deliberation session.

  ┌─────────────────────────────────────────────────────┐
  │                    AGENT                            │
  │                                                     │
  │  ┌──────────────┐   ┌────────────────────────────┐ │
  │  │   PERSONA    │   │         SUBSTRATE          │ │
  │  │  (role def)  │   │  memory · LLM · compaction │ │
  │  └──────────────┘   └────────────────────────────┘ │
  │                                                     │
  │  ┌──────────────────────────────────────────────┐  │
  │  │           DELIBERATION LOOP                  │  │
  │  │  receive → reason → propose → gate → emit    │  │
  │  └──────────────────────────────────────────────┘  │
  └─────────────────────────────────────────────────────┘

Step 1 — Define a persona

A Verdaca persona is a role card: a name, a functional role description, a constraint list, and an output format specification. The kernel uses the constraints to gate proposals during deliberation — write them as specific exclusion rules, not aspirational principles.

from verdaca import Persona

analyst = Persona(
    name="competitive-analyst",
    role="Evaluate strategic claims for competitive validity and market-evidence support",
    constraints=["Do not accept claims without cited evidence or named comparables", "Flag any assumption dependent on market conditions more than 12 months old"],
    output_format="structured-finding-list",
)

Step 2 — Implement adapter bindings

By default, custom personas use the session's configured memory adapter. Override only if your persona requires different persistence semantics — for example, a stateless fact-checker that should never carry session memory across rounds.

from verdaca.adapters import MemoryAdapter

class CustomAdapter(MemoryAdapter):
    def store(self, key, value):
        # Persist value under key using your backing store's write interface
        ...
    def retrieve(self, key):
        ...
    def search(self, query, top_k=5):
        ...

IMPORTANT

Subclass against the adapter protocol version your verdaca.yaml declares; a mismatch between the declared contract version and your implementation will raise a conformance error at session creation, not at runtime.

Step 3 — Register and run

Attach the persona to a session, pass a deliberation prompt, and set the number of reasoning rounds. Three rounds is the recommended minimum for adversarial tasks; single-round is acceptable for structured extraction.

session = Studio.create(memory=CustomAdapter())
session.add_persona(analyst)

result = session.deliberate(
    prompt="Evaluate the competitive positioning claims in the attached strategy memo",
    rounds=3,
)

Testing your agent

Run the AgentTestHarness against your persona before putting it in a production session. A pass rate below 90% indicates under-specified constraints or a role description that conflicts with the output format.

ADVISORY

At minimum, test each constraint in isolation with a prompt designed to violate it, and test the output format against the kernel's parser before your first live session.

from verdaca.testing import AgentTestHarness

harness = AgentTestHarness(analyst)
report  = harness.run_suite("competitive-analyst-conformance")
assert report.pass_rate >= 0.90

Next steps

Workflow recipes — pre-built patterns to adapt
Output review — evaluate deliberation quality