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 execution 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. For direct hosted-client onboarding, use the Weavz MCP App so the user signs in from the MCP client, chooses a workspace during authorization, and receives a workspace-scoped Code Mode connector.
  7. Execute actions or enable triggers inside the workspace. When the same integration appears more than once, target it with workspaceIntegrationId or integrationAlias.
  8. Choose the discovery path. Use runtime integration metadata for dynamic catalogs and setup UIs, TypeScript generated helpers for compile-time known action inputs, Python generated Pydantic models for local validation, and MCP Code Mode declarations for agent runtime tool calls.
  9. 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
Weavz MCP AppGeneric remote MCP connector that provisions or reuses a Code Mode server after user sign-in and workspace selection
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
SDK generated catalogGenerated TypeScript action types and Python Pydantic models for known integration/action pairs

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 the Weavz MCP App when the first user interaction should happen inside Claude, ChatGPT, Codex, Cursor, or another remote MCP client.
  • Use TOOLS mode for constrained servers with a small, explicit tool list.
  • New MCP servers default to OAuth, restricted end-user access, and settings.codeMode.approvalWaitSeconds: 0. Set authMode, endUserAccess, endUserId, or settings.codeMode.approvalWaitSeconds only when the client or approval flow needs those behaviors.
  • 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 execution policy in workspace integration settings, not in action input.
  • For actions and triggers, target repeated integrations with workspaceIntegrationId or integrationAlias, pass endUserId for per-user connection resolution, and use partialIds when defaults or enforced values should be explicit.
  • Add Human Gates before exposing high-risk tools to MCP clients.
  • Use client.integrations.get() or GET /api/v1/integrations?name=... for runtime action/property metadata.
  • Use TypeScript ActionInput<I, A>, integrationActions, and isKnownActionName() for compile-time known SDK calls.
  • Use Python get_action_input_model(), validate_action_input(), and client.actions.execute_typed() for local Pydantic validation before SDK execution.

Key References