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.

Your custom agent runs behind the same authenticated gateway as any catalog persona — inbound requests clear the auth-first spine (signature, identity, replay, budget) before reaching it. See the front door.

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

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 anatomy An Agent binds together a Persona (role card, constraints, output format) and a Substrate (memory, LLM proxy, compaction adapters), both feeding the five-phase deliberation loop: receive, reason, propose, gate, emit. AGENT ANATOMY AGENT PERSONA Role card · constraints · output format SUBSTRATE Memory · LLM proxy · compaction adapters DELIBERATION LOOP receive → reason → propose → gate → emit Persona, substrate and loop bind together before the kernel admits the agent to a session.

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