Agent frameworks

Microsoft Agent Framework

vincs[agent-framework] is a context provider for Microsoft Agent Framework. It adds the relevant part of your Vinc graph to each run, and writes only when your code asks.

Install

pip install "vincs[agent-framework]"

Requires Python 3.11 or later. This extra installs agent-framework-core 1.8.1 or later alongside the SDK and account CLI. A read-only key (vinc_ro_) is enough for the providers and tools; only record_episode and write_package need a write key.

This page describes vincs 0.1.5, which carries vinc-agent-framework 0.1.8. The separate vinc-agent-framework package has the same names under vinc_agent_framework.

Role mode or context mode

VincContextProvider runs in role mode when you pass prefetch_role, and in context mode when you do not. Both read once per run, in before_run.

The tool rule comes with vincs 0.1.4; vincs 0.1.3 does not apply disallowed_tools. With expose_tools=True, the model's own lookups add up to 4 calls per run in either mode.

Add context to every run

Add VincContextProvider to context_providers. Before each run it looks up the newest user message in Vinc and, when something matched, adds a block to the instructions. The block is marked as reference data and cites node ids the model can quote back.

from agent_framework import Agent
from agent_framework.openai import OpenAIChatClient
from vinc.integrations.agent_framework import VincContextProvider

vinc = VincContextProvider()              # reads VINC_API_KEY; use a vinc_ro_ key
agent = Agent(
    client=OpenAIChatClient(),
    instructions="You review design changes.",
    context_providers=[vinc],
)
await agent.run("Why are our colour tokens stored as OKLCH?")

In context mode, if Vinc is unreachable or the daily limit is used up, the run goes ahead without the block. With prefetch_role the run stops instead. A wrong key or space raises.

Let the model look things up

VincContextProvider(expose_tools=True) adds two read-only tools, vinc_brief and vinc_search. To build them yourself, use create_vinc_tools(client).

Record after a person approves

The provider never stores the conversation: its after_run does nothing. When a person has approved the result, record it yourself with a write key.

import os
from vinc import AsyncVincClient
from vinc.integrations.agent_framework import record_episode

writer = AsyncVincClient(api_key=os.environ["VINC_WRITE_KEY"])   # vinc_sk_
await record_episode(
    writer,
    "Fixed contrast on the dark secondary button",
    summary="text-secondary now passes 4.5:1 on the dark surface.",
    about=["decision:tokens-are-oklch"],
)

Retry the record step

From vincs 0.1.4, record_episode and write_package take create_only and operation_id and pass them to the client unchanged.

• Before asking a person, store a fresh lowercase UUID next to the episode id in your host state, and pass it as operation_id on every attempt of that write. An identical retry returns the stored result without applying again.
• With an operation_id, the client also retries the write itself while the hub is briefly down. After an uncertain response (VincUnavailable), read await writer.operation_status(operation_id) before deciding. accepted and unknown do not prove the write did not happen.
• With create_only=True, an episode id that already exists is refused. Retry such a write with the same operation_id, or the retry is refused because the first attempt created the episode.
• Delete and merge are not wrapped here. Call the client's delete, delete_edge, merge_nodes or doc_delete with dry_run=True first, then apply with the preview_digest it returns. See the Python SDK.

Run the agent as a Vinc role

Pass prefetch_role to VincContextProvider. Before every run it reads that role's whole contract, the full text of the documents the role says to read first, and Vinc's material on the task, with node ids the model can cite. The model gets the evidence without having to decide to look it up.

from agent_framework import Agent
from agent_framework.openai import OpenAIChatClient
from vinc import AsyncVincClient
from vinc.integrations.agent_framework import VincContextProvider

reader = AsyncVincClient()                             # vinc_ro_ key
agent = Agent(
    client=OpenAIChatClient(),
    instructions="Review the proposed change.",
    context_providers=[VincContextProvider(
        reader, prefetch_role="concept:agent-reviewer-judgement", expose_tools=True,
        prefetch_max_chars=120000,
    )],
)

Prefetch reads the complete role contract and each required document by its declared document id on every run, without a cache. Each document must have complete text and a verified content hash; missing, partial or unverified documents raise prefetch_spec_unresolved before optional task lookup. Authentication and service errors propagate, so the run stops before the model is called. The combined prefetch_max_chars budget defaults to 24,000 characters. Large roles need a larger budget, such as the 120,000-character budget in this example. prefetch_budget_exceeded stops the read instead of truncating the contract or required documents. Your code picks the role and its budget. Helpers use max_chars for this same budget.

To keep the agent on the contract you reviewed, pin the role. Read it once, keep its hash, and pass it as prefetch_pin. When someone has changed the role (its props, title, topic or relations), before_run raises VincRoleChanged with the current rev and hash in details, and the model is not called. Moving the pin to the new hash is your decision. The pin covers the role contract, not the text of the documents it lists. The prefetch helper takes the same value as pin. It comes with vincs 0.1.5.

pin = (await reader.role("concept:agent-reviewer-judgement"))["hash"]    # after you reviewed it
provider = VincContextProvider(
    reader, prefetch_role="concept:agent-reviewer-judgement",
    prefetch_max_chars=120000, prefetch_pin=pin,
)

Check the final answer against the role

VincOutputGateMiddleware checks the final response outside the model, against the role's gates, never_checks and person_only. On block or a pending approval it raises OutputGateStopped. It calls no model and writes nothing.

from vinc import OutputGate
from vinc.integrations.agent_framework import VincOutputGateMiddleware

role = await reader.role("concept:agent-reviewer")     # read fresh for this run
gate = OutputGate(role["props"])
agent = Agent(
    client=OpenAIChatClient(),
    instructions="Review the proposed change.",
    middleware=[VincOutputGateMiddleware(gate)],
)
await agent.run("Review the proposed change.")         # run(), not a stream

• Streaming is refused before the agent runs, so unchecked tokens cannot leave through it. Put it outermost if other middleware changes responses.
• A claim that something ran, such as tests passing, needs evidence your host saw in this run, passed through the evidence callback. The model's own word never counts.
• A role whose contract is prose only, or names a check the gate does not know, blocks. The gate stops output; it does not grant or take away tools. Role mode keeps tools named in disallowed_tools out of the run; leave any other tool the role must not use out of the agent.

Ask a person before a person-only step

Have the model step answer with a vinc.RoleOutput and connect a VincPersonOnlyExecutor after it. When the answer asks for a person-only action, the workflow emits the framework's own request_info event. Send the person's decision back as the response; the model is not called again.

from agent_framework import WorkflowBuilder
from vinc import ApprovalDecision
from vinc.integrations.agent_framework import VincPersonOnlyExecutor

approval = VincPersonOnlyExecutor(gate, role_id=role["id"], run_id="review-1")
workflow = WorkflowBuilder(start_executor=model_executor).add_edge(model_executor, approval).build()

decision = ApprovalDecision(request_id=event.data.request_id, approved=True)
await workflow.run(responses={event.request_id: decision})

A rejected answer has nothing to deliver, and approval never overrides a block. Approval releases this answer only; it does not run or permit any tool. Configure workflow checkpoints if a pending approval must survive a restart.

Hand off to another agent

Passing only citation ids loses the first agent's conclusion. Instead, the first agent writes one package Record with the question, the conclusion and each claim's evidence, and the next agent reads it by id.

from vinc.integrations.agent_framework import PackageProvider, write_package

handoff = await write_package(                         # first agent, vinc_sk_ key
    writer, "When does the dashboard become stale?", "Keep the 36 hour threshold.",
    claims=[{"claim": "Stale after 36 hours.", "evidence_ids": ["decision:threshold"]}],
    produced_by="agent:analyst", run_id="analysis-1", space="personal",
)
receiver = Agent(
    client=OpenAIChatClient(),
    instructions="Review the prior conclusion and cite available evidence.",
    context_providers=[PackageProvider(reader, handoff["package_id"], space=handoff["space"])],
)

Name the space; the evidence must already exist there. PackageProvider rereads the package before every run and checks each evidence id with the reader's own key, so deleted or unreadable evidence is marked as not citable. Bind one provider per handoff.

Structured review, one retry

run_review(agent, messages) asks for a ReviewOutput: a verdict of ACCEPT or RETURN, findings with citations, and person-only requests. A malformed answer gets one retry. A second failure raises UnparsedReview instead of passing as an empty review; hand that to a person. Each attempt runs with tools turned off.

from vinc.integrations.agent_framework import UnparsedReview, run_review

try:
    review = await run_review(reviewer_agent, "Review this draft against its cited rules")
except UnparsedReview:
    raise                                              # stop here and hand it to a person

Every helper

Import them from vinc.integrations.agent_framework. The functions take an AsyncVincClient first and are awaited.

Over MCP instead

Agent Framework can also reach the Vinc MCP server directly. Keep the tool list to reads, and set load_prompts=False if you do not use role prompts.

import os
from agent_framework import MCPStreamableHTTPTool

vinc = MCPStreamableHTTPTool(
    name="vinc", url="https://mcp.vincs.io/mcp",
    static_headers={"Authorization": "Bearer " + os.environ["VINC_API_KEY"]},
    allowed_tools=["vinc_brief", "vinc_search"],
    load_prompts=False,
)