Connect

Agent frameworks

Vinc gives your agents the decisions and records your team already wrote, with where each came from. The vincs package includes the SDK and account CLI, with optional support for LangGraph, LangChain and Microsoft Agent Framework.

If the agent has to follow its role's contract (what it must never do, its gates, the tools it may not use), use role mode. Role mode stops the run when Vinc cannot be read; context mode goes on without context. The table below compares them.

One package, optional frameworks

Feature	For	Install
Python SDK + CLI	Any Python code and account graph commands.	`pip install vincs`
LangChain + LangGraph	Graph helpers, tools and create_agent middleware.	`pip install "vincs[langgraph]"`
Microsoft Agent Framework	Context provider and workflow helpers.	`pip install "vincs[agent-framework]"`

Requires Python 3.11 or later. Install "vincs[all]" for both frameworks. Set your key in VINC_API_KEY. The SDK and adapters connect to your account graph. Local storage and offline models require the standalone desktop or CLI runtime. Other frameworks connect over MCP: Other frameworks.

How they work

The framework adapters do three things.

Before a model call, it looks up the newest user message in Vinc and adds what matched to the system message, as a block marked as reference data rather than instructions.
When the model wants to look further, it offers two read-only tools, vinc_brief and vinc_search.
After a person approves the result, your code calls record_episode to write what happened back to Vinc.

None of them store the conversation. Writing back happens only when your code calls it.

The current release is vincs 0.1.5. It carries vinc-client 0.1.12, vinc-langgraph 0.1.9 and vinc-agent-framework 0.1.8, and each page names the release a newer feature came with. Role evidence, output gates, approval steps and handoffs are switched on in your code. To get everything these pages describe, install vincs>=0.1.5,<0.2.

Role mode or context mode

The context step (VincContextMiddleware in LangGraph, VincContextProvider in Agent Framework) runs in role mode when you pass prefetch_role, and in context mode when you do not.

Mode	When Vinc is unreachable or the daily limit is used up	Reads per run (hub calls)	Tools the role disallows	Pinning
Role mode (`prefetch_role`)	The run stops before the model is called. There is no retry, and any failed read stops it the same way.	Once per run: 1 call for the role, 2 per required document (the document and its node), 1 brief and 1 search.	Kept out of the tools the model sees, and a call to one is refused. Names must match exactly.	Optional, from vincs 0.1.5: with `prefetch_pin` set to a contract hash from `role()`, a run whose role has changed stops before the model is called. Without it each run reads the role as it is when the run starts. Either way a run keeps its contract to its end.
Context mode (no role)	A warning is logged and the model call goes ahead without context. A wrong key or space raises.	1 brief, plus a search when it ties or finds nothing. LangGraph reuses the result for 60 seconds; Agent Framework reads once per run.	Not applied: there is no role.	Not applicable: each lookup reads the graph as it is.

The per-run read in LangGraph and the tool rule come with vincs 0.1.4. With vincs 0.1.3, LangGraph reads the role before every model call and neither adapter applies disallowed_tools. If you give the model the read tools, they add up to 4 calls per run in either mode.

Two keys

Make keys on your vincs.io account page. Give the reading parts a read-only key (vinc_ro_) and only the step that records after approval a write key (vinc_sk_). Then even if a model is talked into calling a tool it should not, it cannot change the graph.

export VINC_API_KEY=vinc_ro_...     # reading
export VINC_WRITE_KEY=vinc_sk_...   # the recording step only

For a team's graph, pass space="<team id>". Without it you reach your personal graph.

Running an agent as a role

A role in Vinc (Agents) can drive a framework agent. The packages read the role from Vinc each time, so the agent follows whatever the role says today, without a copy in your code.

from vinc import VincClient

reader = VincClient()                                  # vinc_ro_ key
role = reader.role("concept:agent-reviewer-judgement")           # the stored contract, read now
block = reader.prefetch(
    "concept:agent-reviewer-judgement", "Review the proposed change.",
    max_chars=120000,
)

In a framework, pass prefetch_role to the context step (VincContextMiddleware in LangGraph, VincContextProvider in Agent Framework), add the output gate, and add an approval step for person-only actions. The framework pages show each.

Reading the role each time means a change to the role reaches the next run. To keep an agent on the contract you reviewed, pin it: role() returns the contract with its rev and hash, and you pass that hash as pin (prefetch_pin in a framework). When the role has changed, the read raises VincRoleChanged and the run does not start. Moving the pin to the new hash is your decision. The pin covers the role contract, not the text of the documents it lists. It comes with vincs 0.1.5.

In the role	In the framework
`mission`, `reads`	`prefetch_role`: read with citable ids once per run (role mode)
`gates`, `never_checks`	The output gate (`OutputGate`) on the final answer
`person_only`	The output gate, then an approval step (`create_person_only_node` in LangGraph, `VincPersonOnlyExecutor` in Agent Framework)
`disallowed_tools`, `tools`	The tool list you give the agent. In role mode, tools named in `disallowed_tools` are kept out of the run
`rung`	The model you choose
`writes_graph`	What `record_episode` and `write_package` write after approval

The gate checks only what the role lists as checks (gates, never_checks); the rest of the role's prose still binds whoever runs the agent. Tools and the model stay your choice. In role mode a tool whose name is in disallowed_tools is kept out of the run; leave out by hand any tool the role forbids under another name, and pick the model by rung. Choosing a role grants no permission.

What to expect

Ordinary context lookup costs one read, or two when it widens to search. LangGraph can reuse the result for 60 seconds by default; Agent Framework reads before each run. Calls count against your daily limit.
In context mode, if Vinc cannot be reached or the daily limit is used up, the model call goes ahead without the block. Role mode stops the run instead. A wrong key or space raises an error in both, because it will not fix itself.
Vinc does not pick a role for a task. Your code chooses the role.
Role prefetch reads the complete contract, full required documents and task evidence once per run and keeps nothing between runs (LangGraph in vincs 0.1.3 reads before every model call). Each read costs 3 calls plus 2 per required document.