Agent Implementation Model

Canonical build order and product primitives for agents implementing Weavz.

Agent Implementation Model

Use this page as the implementation mental model for Weavz. The product is organized around workspaces, configured integrations, connection resolution, agent access, and guarded execution.

Canonical Build Order

  1. Create or choose a workspace. Treat it as the product, tenant, project, personal user, or agent integration hub.
  2. Add workspace integrations with stable aliases. Configure connection strategy, enabled actions, built-in persistence, and sandbox policy on the workspace integration.
  3. Add connections and end users. Use fixed for shared service accounts, per_user for user-owned auth, and per_user_with_fallback when a default connection can be overridden by a user connection.
  4. Add input partials for reusable defaults or locked parameters. Add Human Gates before agents can perform sensitive sends, writes, spend, exports, destructive operations, or actions that use end-user credentials.
  5. Create an MCP server for the workspace. Use CODE mode for broad agent workspaces and TOOLS mode for small explicit tool surfaces. Workspace integrations sync into MCP servers automatically.
  6. Execute actions or enable triggers inside the workspace. When the same integration appears more than once, target it with workspaceIntegrationId or integrationAlias.
  7. Validate the complete setup in Playground, then automate the same structure with REST, the TypeScript SDK, or the Python SDK.

Primitive Map

PrimitiveWhat it means
WorkspaceThe scoped integration hub for a product, tenant, project, or agent environment
Workspace integrationA configured integration instance with alias, connection strategy, enabled actions, and optional settings
ConnectionThe encrypted credential for a third-party service
End userYour app user's identity for per-user auth and state
Input partialSaved defaults or enforced parameters for actions and MCP tools
Human GateApproval policy that pauses sensitive execution until a reviewer decides
MCP serverAgent access surface for workspace integrations
Storage/KVBuilt-in persistence for files and key-value state, scoped by end user, workspace, or external namespace
Code ModeMCP mode with weavz_search, weavz_read_api, and weavz_execute for dynamic multi-step agent work

Default Choices

  • Use workspace integrations and aliases instead of raw connections when embedding Weavz into a product.
  • Default to one workspace per tenant, team, project, or agent environment. Use a workspace per user for personal-agent products or strict isolation where each user needs separate integrations, state, MCP servers, approvals, and quotas.
  • Use end_users inside a shared workspace when users share the same integration environment but need their own credentials and state.
  • Use CODE mode for agent-facing workspaces with many actions or multi-step workflows.
  • Use TOOLS mode for constrained servers with a small, explicit tool list.
  • Configure Storage, KV Store, Agent Memory, Agent Scratchpad, Sequential Thinking, HTTP, Web Reader, Data Transformer, Code, and Advanced Code as workspace integrations before agents need them.
  • Keep persistence and sandbox policy in workspace integration settings, not in action input.
  • Add Human Gates before exposing high-risk tools to MCP clients.

Key References