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. Choose the agent access surface. For direct hosted-client onboarding, use the Weavz MCP App at /mcp/weavz so the user signs in from Claude, ChatGPT, Codex, Cursor, or another MCP client, chooses a workspace during authorization, and receives a workspace-scoped Code Mode connector. For a curated or programmatically provisioned endpoint, create an MCP server for the workspace.
  6. Use Code Mode for broad agent workspaces and Tool Mode for small explicit tool surfaces. Workspace integrations sync into MCP servers automatically.
  7. For app-owned agent harnesses, create an MCP server with authMode: "oauth_and_bearer" and issue per-end-user MCP bearer tokens. Direct action execution is secondary and fits smoke tests, backend jobs, trigger workers, and non-MCP product flows.
  8. Execute actions directly or enable triggers inside the workspace when a backend workflow needs that surface. When the same integration appears more than once, target it with workspaceIntegrationId or integrationAlias.
  9. 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.
  10. 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
Filesystem/State KVBuilt-in persistence for files and key-value state, scoped by end user, workspace, or custom namespace key
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 per-end-user MCP bearer tokens when your SaaS backend owns the agent harness and needs to hand it an MCP URL plus Authorization: Bearer mcp_....
  • Use Tool 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 Filesystem, State KV, Agent Memory, Agent Scratchpad, Sequential Thinking, HTTP, Web Reader, Data Transformer, JavaScript Sandbox, and Sandbox 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