iGentic
iGentic 2.0 runs agent flows: a GroupAgent flow has an orchestrator that hands work to member agents, a SingleAgent flow has members only. Beak sees those agents in three steps, and each step is a choice you make, not something that happens because a connector was saved.
- Discover — the iGentic integration lists every flow's orchestrator and agents into the Agent Registry as candidates.
- Adopt — pick the agents to govern, give each an owner, and choose how Beak stands on their path: Gateway mode or Hooks mode.
- Wire — on the iGentic side, set three values once for the deployment. Nothing is configured per agent: every call names the agent by its own iGentic GUID.
Both modes use one integration key for the whole deployment. Generate it from the iGentic card in Integrations; it is shown once. The same value is the bearer token for the hooks and the API key for the Gateway, so an iGentic deployment holds exactly one Beak secret.
Which mode
| Gateway mode | Hooks mode | |
|---|---|---|
| Beak sees | Every prompt, every completion, tokens and cost, model allowlists | Every prompt and completion, every tool call and its result |
| Beak enforces | Prompt block or redact before the model; per-agent budgets and allowlists; tool calls through the hooks | Prompt and completion block or redact; tool call deny, escalate, or result withheld |
| Cost governance | Yes — spend lands on the agent | No — the vendor meters the call |
| What iGentic changes | Model endpoint and key, plus the agent header on each request | Four calls from Semantic Kernel filters |
| Fails | Prompt scan fails open with a governance event; budget and authorization fail closed | Prompt and completion calls fail open with a governance event; tool calls fail closed |
Choose Gateway mode when cost and model governance matter and the deployment's model client can be repointed. Choose Hooks mode when the model path has to stay iGentic's. The two are not exclusive: a Gateway-mode agent can also send tool hooks, since iGentic's tools are its own functions and never pass through the Gateway.
Gateway mode
How the key works
iGentic holds the integration key. Beak holds a per-agent key for every adopted agent, minted at adoption, bound to the agent's identity, and never shown to anyone. On each request iGentic sends the integration key plus the agent's GUID; the Gateway resolves the per-agent key from the two and proceeds as if that key had been presented. Spend lands on the agent within the deployment's ceiling, the audit row names the agent's identity, and the agent earns gateway.llm.
An agent that nobody adopted is refused with agent_not_adopted. The Gateway reports the refusal to Beak AI Security, and the Onboarding posture panel on Agent Governance lists it as refused at the Gateway, not adopted (medium) for 24 hours after the last refusal, naming the agent when the connector has already found it. That is the strongest onboarding evidence there is: the agent is live and calling an LLM while ungoverned. Adopt the agent and the next call succeeds. A request on the integration key with no agent header is refused too; the key can never spend anonymously.
What to set on iGentic
iGentic's model client is Azure OpenAI shaped, and the Gateway serves that shape:
| Setting | Value |
|---|---|
| Azure OpenAI endpoint | https://<your-beak-host>/api/aigateway |
| Azure OpenAI API key | the integration key |
| Deployment name | the Gateway model id (for example gpt-4o) |
| Per-request header | x-beak-agent-id: <the agent's iGentic GUID> |
The header is the one code-level change: an outgoing-request handler on the Azure OpenAI client that stamps the GUID of the agent making the call. Without it the Gateway cannot tell one agent from another and refuses the request.
You do not have to assemble these values by hand. The iGentic card under Integrations has an Integrate iGentic panel that prints them for the Beak host you are signed in to, with a copy button per mode; the endpoint there is the one to use, whether you reach Beak through the platform host, your tenant's branded host or the product host. Once the integration key exists, the panel also lists the deployment names iGentic may use: the model ids allowed for the Gateway team the key is bound to, or every active Gateway model when that team has no allowlist.
Hooks mode
iGentic calls Beak four times per turn from its Semantic Kernel filters. Every call carries the integration key as a bearer token and names the agent by GUID in agent_id.
| When | Call | What Beak answers | What iGentic does with it |
|---|---|---|---|
| Prompt rendered, before the model | POST /aisecurity/hooks/prompt with messages since the last assistant turn (tool results included) | action of allow, warn, log, redact or block, with redacted_text when redacting | block refuses the turn; redact sends the model redacted_text |
| Completion received, before it is returned | The same route with direction: "output", response, and caller_applies_verdict: true | The same shape, enforced: true | block withholds the answer; redact returns redacted_text |
| Function about to run | POST /aisecurity/hooks/tool?format=beak with tool, inputs, context | allow, deny, or escalate with a resume_token | deny does not run the function; escalate polls GET /aisecurity/hooks/tool/approvals/<resume_token> |
| Function returned | The same route with direction: "output" and result | allow, redact with redacted_text, or block | block does not hand the result to the model; redact hands it redacted_text |
Prompt and completion calls fail open: on a timeout or error iGentic continues and Beak records the gap. Tool calls fail closed: on a timeout or error the function does not run. State the timeout in iGentic's configuration; a hook that is not on the record is a hook nobody can reason about.
What gets stored
Every call leaves a row in the same ledger the Gateway writes — the scanned prompt, completion, tool inputs or tool result, the verdict, and the agent — so Incidents, Compliance and the Agent Registry's evidence view work for an iGentic agent exactly as they do for a Gateway one. Hook-sourced rows keep the whole scanned span rather than the Gateway's excerpt, because for a platform calling in, the row is the only record of what was said.
Completion verdicts from a hook are enforcements: the caller holds the answer until Beak answers, and says so with caller_applies_verdict. The Gateway's own completion scans stay detection-only, because by the time they run the answer has streamed.
The operator sequence
- Save the iGentic integration and discover the agents.
- On the same card, Generate integration key. Copy it once.
- Adopt the agents to govern. On the level step, choose Full Gateway for Gateway mode, or Both hooks (Level 2 and Level 3 together) for Hooks mode. Start in log mode.
- Hand the integration snippet from the wizard to whoever operates iGentic. It carries the exact calls or settings for the mode you chose.
- The wizard's verify step turns green on the first prompt event and the first tool event from each agent. Then switch iGentic to enforce.
Adoption comes before enforcement. Tool authorization refuses an agent that is only discovered, and in Gateway mode so does the key resolution. Log mode makes both visible before either bites.
Best Practices
- Generate the integration key once per iGentic deployment and keep it in the deployment's secret store, not in an agent's configuration. The per-agent keys are Beak's; nothing on the iGentic side ever needs them.
- Start every agent in log mode and watch the verify step. Enforcement before adoption refuses calls by design; log mode shows you which agents would have been refused before it bites.
- Adopt agents, do not just discover them. A discovered iGentic agent is inventory and identity only, and in Gateway mode its calls are refused until it is adopted.
- State iGentic's hook timeouts in its configuration. Prompt and completion calls fail open with a governance event; tool calls fail closed. A timeout nobody wrote down is a governance decision nobody made.
- Rotate the integration key from the card, not by generating a new one elsewhere. Rotation re-parents every held per-agent key; a key created any other way governs nothing.
- Keep tool calls on the tool hook even in Gateway mode. iGentic's functions never pass through the Gateway, so the Gateway alone cannot see them.
Related Pages
- Integrations — the discovery connector and the integration key
- Agent Onboarding — levels, boundaries, the prompt hook and the tool-hook receiver
- Agent Registry — where discovered iGentic agents appear
- Beak AI Gateway virtual keys — the key model the integration key builds on