Agent Factory

Create an agent, give it knowledge and capabilities, test it and publish versions your application calls through a stable address — without assembling SEIF's internal records yourself. Everything happens in one place: the Agent Workspace of the Workstation.

Start here: the Agent Workspace

Open the Workstation. The home screen says Create your first AI agent and offers five editable starting points: Start from scratch, Customer support, Game character, Tutor and Assistant for an application. Pick one, describe what the agent should do, and choose Create agent. New agents live in a workspace folder (by default ~/Documents/SEIF Agents/My agents); one workspace holds many agents that can share knowledge explicitly.

Each agent has the same sections, in the order you normally need them:

The top bar always shows the workspace and agent, the environment you are looking at, whether a real model or rehearsal answers, and the Agents | Context engineering switch. The sidebar marks each section done (✓), needing attention (●), to do (○) or waiting on an earlier step (■), and the agent card says both what state the draft is in and what is live.

Context engineering is the expert view of the same project: Context Profiles, rules and budgets, the knowledge map, immutable Context Builds, the Registry, environment bindings, traces and historical investigation. Agents are built on exactly those records; nothing is duplicated. Projects created from context templates, and existing context projects, open there.

What the simple words mean

Projects made of files: a team, a World project

The Agent Workspace opens projects made of files (seif.yaml) as they are, with no conversion: every agent of the project is listed, a team's members included (Team → Setup → Agent Workspace…, World → 🤖 Agents). An agent is its files:

In these projects the development model is the project's brain (Data & go live), Capabilities also lists the built-in ones (shared documents, the web, connected data, usage, preparing messages) next to Tool contracts, Needs you is the project's one queue, and a release can be served on Go live (Releases → Serve on Go live, Integrate → Go live). Context engineering of these projects is the Lab. See One agent system.

Your first agent

1. Create. Choose a starting point, name the agent and say what it should do.
2. Connect a model. In Model, choose Claude (the key is kept in this computer's vault, the same key Go live and the Team use; on the web, the account key), Use an installed CLI (Codex, Claude Code or Kiro CLI), a discovered Ollama model (on this machine or OLLAMA_HOST), or an OpenAI-compatible API. The connection is checked with one minimal request. CLI accounts keep their own login; API keys are vault entries or environment variables and never enter the agent or project. Rehearsal is explicit and labelled no AI: deterministic placeholder replies that prove the plumbing, never quality, and never publishable to production. Every provider comes from the one model layer the Team and Go live use (One agent system).
3. Try it. Talk to the unpublished draft. Draft preview runs only outside production, creates no release or route and is not counted as published traffic.
4. Add knowledge, add capabilities, run tests, create a release, publish and integrate — the Overview always names the next step.

Use an installed CLI

Open Model → Use an installed CLI, choose Codex, Claude Code or Kiro CLI, and click Use … and check. Leave the model blank to use the client's default or enter a model supported by your account. Discovery only checks the executable and version; the explicit connection check makes one model request. Then open Try it to talk to the draft.

The executable runs on the agent service's computer. A local CLI may send inference to its provider's cloud, using that account's limits; it is different from an Ollama model running locally. The server console offers the same provider choice and connection check. A remote server needs its own installed clients and authentication.

Advanced settings → Executable accepts an absolute path, including paths containing spaces. macOS GUI launches also search ~/.local/bin, ~/.npm-global/bin, /opt/homebrew/bin and /usr/local/bin, without sourcing shell startup scripts. Missing executables, authentication failures, timeouts and invalid responses produce a failed check with a next step. Saving a connection alone does not prove it works.

The binding is environment configuration, for example {"provider":"subscription-cli","engine":"codex","model":"default"}. The optional executable is a path, never a shell command; arbitrary arguments are refused. Kiro additionally accepts secretRef, naming its credential variable. Codex and Claude Code reuse their saved login (CODEX_HOME and CLAUDE_CONFIG_DIR are respected). Application tokens and unrelated API keys are excluded from the child environment.

This transport adapts Estuda AI's packages/llm-adapter-subscription-cli protocol to the same LLMProvider interface already used by the factory, without depending on another checkout. Instructions, history, offered tool schemas and tool results travel through stdin. Each call uses a temporary working directory. Client tools and automatic MCP discovery are disabled; application capability calls return to the existing SEIF gateway for validation and approval. Output is bounded; cancellation and deadlines terminate the process group. Codex uses ephemeral runs and Claude disables session persistence; Kiro may retain sessions in its own user storage. Tokens are labelled not reported when the client provides no usage; zero is not a measured token count.

Connection changes invalidate evaluations. Leaving model selection at default allows the client's default model to change after updates; choose an explicit model for repeatable evaluations. Executables, authentication and model availability must be configured again on a destination server; releases do not bundle CLI installations or accounts.

The integration follows the official references for Codex non-interactive execution, Claude Code CLI, Kiro headless mode and Kiro agent configuration. Automated coverage uses executable process fixtures for all three clients and the native interface; it does not establish authenticated access to a provider account.

Try it

Three modes are always distinguishable:

Each turn shows the version that answered (draft digest or release), the model, latency, provider-reported tokens, cost (not measured unless pricing is configured), the knowledge received and not received with reasons (not given to this agent, nothing relevant to this message, left out to fit the budget, …), capabilities available and unavailable with reasons, capability calls and their outcomes, approvals waiting, and a plain-language Why this answer. Technical evidence holds the structured record. Save as a test scenario turns a conversation into a scenario whose expectations you write; the reply is never copied as an expectation.

Unsaved behavior edits are not used by Try it or Tests until saved, and the page says so. Long model calls can be abandoned with Stop waiting; the agent service may still finish them, and the page says that too.

Knowledge

Write information, Add a document (Markdown, text, JSON, CSV, YAML, HTML or XML up to 1 MiB, copied into the workspace's knowledge/ folder so the project stays portable) or Connect a folder (retrieved by relevance within the budget). Each item shows its source, whether it is available, how many items it contains, when it was last checked and which agents use it. Credentials in knowledge are refused.

See what the agent would receive resolves the context for a message without calling a model: what would be selected, what would not and why, and the budget. Editing knowledge marks every affected agent's tests out of date (Knowledge or capabilities changed after the last evaluation. Re-evaluate before publishing.).

The stage vocabulary is preserved underneath: available, applicable, desired, selected, materialized, projected, rendered and consumed remain distinct in traces and in Context engineering.

Capabilities

A capability lets the agent ask one of your systems to look something up or to act. The guided form asks for a name, a purpose, the inputs (name, type, required, description, allowed values) and optionally the result fields; it generates a bounded JSON Schema with additionalProperties: false. Edit as JSON Schema (advanced) accepts nested contracts; a contract the form cannot represent losslessly always opens in advanced mode and is never flattened. Unsupported keywords are refused, not ignored. Changes data capabilities always require operator approval of the exact arguments, at most one call per turn by default.

Each capability shows separate facts, never one "connected" badge:

• Contract defined — version and digest computed for you.
• Allowed for this agent — explicit; other agents are listed under Other capabilities in this workspace until you allow them.
• Connected system configured — the address (or API mapping) for this environment.
• Credential available — the referenced secret is present for the agent service.
• Implements this exact contract — checked with describe, with no effect; out of date when the contract or address changes.
• Real test call succeeded — an operator-initiated call through the gateway, never in production.

Two ways to connect:

• Call an existing HTTP API. Choose the method and address, e.g. GET https://api.example.com/customers/{email}. The built-in API adapter runs inside the agent service and implements the executor contract on loopback, so the gateway still checks the exact contract, records dispatch and requires approval for writes. Only declared inputs fill the path or query of the one configured host; read capabilities can only use GET; writes send the remaining inputs as JSON with an Idempotency-Key. A 4xx response is a definite refusal; no answer or a 5xx is an unknown outcome, never reported as success or failure. Your API decides what its credential may do.
• My service implements the SEIF executor contract (GET /describe, POST /execute). Starter code generates a Node.js adapter whose business handler deliberately fails until you implement it.

Run a test call sends a real request with arguments you type. For changes data capabilities you first Review exact arguments, give a reason and Approve exactly these and run; the approval covers that call once. Approvals of agent-proposed actions happen in Try it or Performance; an application credential cannot approve, and the model cannot approve its own action. The tool result tells the model plainly when an action is pending review.

Granting a capability records its exact contract in this agent's own Context Test (and asserts it is offered); revoking removes it; editing a contract re-accepts it only where it was accepted before. Other agents' tests are never changed.

In a project made of files, Built in lists the capabilities every agent may be given without connecting a system: shared documents, the web, connected data, usage of live agents and preparing messages for approval. They are the same list the Team uses for its members (Setup → May) and are kept in the agent's AGENT.md; Tool contracts granted to an agent are also offered when it works in the Team or answers on Go live, through the same executor path.

Tests and readiness

Scenarios are messages with expectations you write: what the reply must mention, must not mention, which capabilities it should use successfully, which actions it should propose. Run tests executes each scenario once against the saved draft, its knowledge and the environment's connections. Context checks (Context Tests for this agent's audience) run first without a model. A passing run is evidence for that exact combination; a generated answer can vary between runs.

The readiness model (GET /api/agents/{id}/readiness) is shared by the Workstation and the server console. It reports the lifecycle — not tried yet, tried, tested, released, not published, published — derived from existing records (draft digest, preview turns, evaluations, releases and routes), why a result is out of date, what is live and whether it was rolled back.

Releases

Create release from this draft is enabled only when the tests passed for this exact draft and connection. Changed or removed scenarios from the previous release require a recorded reason. Publish to development points new conversations to the release; Publish to 10% keeps the current release as baseline for a stable cohort; an older release offers Roll back development to this. Each release lists what changed (instructions, identity, knowledge or capabilities, response contract, scenarios, limits) and whether it is compatible with the release currently serving that environment. Check the published agent sends one real conversation through the published route.

Statuses come from routes and the audit trail: Active, Baseline, Superseded, Rolled back, Not published. Production accepts only releases evaluated with a real model against the production connection with live context connections; rehearsal releases are refused. Agent publication has no separate approver yet: whoever holds the operator credential can publish (see Limitations).

Integrate

The address is POST {FACTORY_URL}/v1/agents/{agentId}/environments/{environment}/turns with an application credential. Integrate shows copyable curl, TypeScript and Python examples, a Send a request as your application check that uses the application credential exactly as a backend would, the outcome-reporting call, and a checklist that separates what is configured from what remains yours (persisting session and request ids, validating proposed actions, enforcing your users' permissions, running the server distribution for continuous operation). examples/agent-workspace/app.mjs is a minimal separate application process.

Server console and standalone server

The standalone server distribution serves the same agent service with a browser server console for remote operators (Agents, Try it with draft preview, Releases, Performance, Channels, Integrate), using the same readiness model, starting points and wording. Knowledge and capabilities for those agents are managed in the Workstation or through the operator API. From the Workstation, Context engineering → Agents ↗ offers the console as an explicitly advanced option.

export SEIF_FACTORY_OPERATOR_TOKEN='<operator credential: at least 24 characters>'
export SEIF_FACTORY_APP_TOKEN='<different application credential>'
./agent-factory --project ./my-project --host 127.0.0.1 --port 4330

In a source checkout use runtime/node runtime/engine/factory-server.mjs instead of ./agent-factory. HTTPS, process supervision and external credential management belong to the deployment environment. With a TLS reverse proxy, configure --public-url https://agents.example.com for exact-origin checks and secure operator cookies. --identities ./applications.json or serviceIdentities on startFactoryServer supports explicit agent/environment scopes and secret references ([{id,secretRef,agents,environments}]). The default application identity serves agents in this project and cannot edit agents, publish, inspect other applications' sessions or approve tools.

Export package in the server console downloads an agent definition, its verified Context Build and embedded knowledge, without credentials, sessions or deployment endpoints. Move it to the standalone server and run ./agent-factory --project ./imported-project --import ./my-agent-v1.json. An empty destination is prepared from the portable context project. Imports into existing projects require the same project identity. Configure the destination model/context connections and publish explicitly; importing never activates a route. A changed connection requires a fresh evaluation and release. The exported model reference does not include model weights.

Operator API for the workspace

All workspace operations are available to scripts with the operator credential: GET /api/starters, POST /api/agents, GET /api/agents/{id}/readiness, POST /api/agents/{id}/preview, GET|POST /api/agents/{id}/knowledge, PUT /api/agents/{id}/knowledge/{layer}, POST /api/agents/{id}/knowledge/separate, POST /api/agents/{id}/inspect-context, PUT /api/knowledge/{source}/text, GET|POST /api/agents/{id}/tools, PUT /api/agents/{id}/tools/{tool}/access, POST /api/agents/{id}/tools/{tool}/test, PUT /api/tools/{tool}, PUT /api/environments/{env}/tools/{tool}/connection, PUT /api/environments/{env}/tools/{tool}/api, POST /api/environments/{env}/tools/{tool}/check, GET /api/models/discover, POST /api/environments/{env}/models/{key}/check, GET /api/agents/{id}/releases. Project edits carry projectRevision; a stale revision is refused (PROJECT_CHANGED). Changes to shared knowledge settings require confirmShared naming every affected audience.

Application contract

POST /v1/agents/{agentId}/environments/{environment}/turns, authenticated with the application credential:

{
  "participantId": "authorized-application-user",
  "sessionId": "optional-existing-session",
  "requestId": "persisted-unique-request-id",
  "channel": "web",
  "message": "Can you help me?",
  "input": {}
}

The response identifies the agent release/digest, session, turn, context Build and trace, model connection digest, provider/model, token usage, latency, tool attempts and output. Application identity, participant, channel and environment constrain session reuse. Initial requests are also deduplicated when the client loses the generated session ID. Preserve request IDs across retries. An interrupted or failed turn is never automatically re-executed: a tool may already have produced an effect. This is bounded suppression, not distributed exactly-once execution.

JSON responses are validated against a bounded JSON Schema subset before application delivery. The game validates proposed actions independently: the NPC can offer the existing lantern quest; only the game can confirm completion or grant its ten coins. Unsupported output/state changes require a new integration contract or agent identifier. Text behavior changes do not require rebuilding the application.

POST /v1/turns/{turnId}/outcomes accepts {reportId, metric, result}. Result is success, failure or unknown; identifiers are idempotent. Metrics group by agent, release, environment and channel. Tokens are provider reported; rehearsal has zero model tokens. Monetary cost remains unknown until pricing is configured. Unreported outcomes remain unknown. A generated response does not imply the user's task succeeded, and comparisons alone do not establish causality.

Releases, sessions and validation

The SQLite store uses WAL and durable writes, with one owner process per project. Agent/context artifacts are digest verified on use. Evaluations bind exact behavior, context compiled for the destination environment and destination model connection. An edit invalidates a previous evaluation. Released regression scenarios cannot silently disappear or change. Add scenarios to evolve the corpus; when product rules legitimately change, the operator reviews changed/removed expectations and records a reason. This review binds the exact candidate and previous release and is invalidated by another edit. Publication supports 10/50/100-percent distribution and restoring prior compatible releases; cohorts are stable per participant. A rollout keeps the original baseline when its percentage changes. Conversation history is bounded and retained for 24 hours by default; sessions, replies needed for duplicate receipts, outcomes and channel-message records expire. Publication and release metadata remain available; audit/evaluation count is bounded. Short-lived memory is not a long-term knowledge store.

Model weights, provider internals and generative answers are not deterministically reproducible. Current evaluations run each declared scenario once. Quality evaluation requires representative scenarios and, where appropriate, repeated trials and human review. Publication verifies declared checks; it cannot certify that an agent is correct for every input.

Tool contracts and Profile selection remain in the Context Build. The factory uses the existing authenticated executor gateway. Read actions execute through it. Writes requiring approval pause as NEEDS_APPROVAL; the reply text then states that the request awaits approval and has not been done (replyBasis: PENDING_APPROVAL_STATEMENT) rather than the model's own wording, which stays on the operator-side turn record. The operator inspects exact arguments and approves through the factory. Approval cannot be supplied by a model or application credential. Expired context plans reject dispatch. Lost executor responses remain unknown; business backends must implement durable idempotency and enforce authorization from trusted application state.

On-demand knowledge remains usable inside a complete agent: when the context offers expandable references, the factory adds the reserved seif_context_expand read tool. The existing runtime validates each reference against this context; at most four expansions are allowed per turn and the agent loop still enforces the overall input budget. Expansion does not grant access to excluded material or perform a business action.

Agent instructions and optional bounded application context are composed with resolved context. Consumption records the actual system message delivered to the provider and correctly reports DIFFERS_FROM_RENDERED when this composition changes the original context message. This is an application-side observation, not proof of provider-internal processing. Context traces use metadata retention; the factory stores bounded conversation data needed for sessions and duplicate receipts until expiry, protected by filesystem permissions. Retention is not encryption or a hosted multi-tenant storage service.

Browser game

Open Channels → Browser gameplay, or /game. The sample uses its own backend endpoints and an HttpOnly player cookie. It receives no factory operator/application credentials. The server owns quest state, inventory, reward validation and outcome reporting. Publish village-guide in development, talk to Lia, pick up the lantern and return it. Change the agent, evaluate and publish v2, then start a new conversation on the same page. Existing conversations continue on v1. The sample game is available only on loopback hosts; production applications should supply their own authenticated backend.

WhatsApp customer care

Channels → Connect WhatsApp binds an agent/environment to an Evolution instance. agent-bindings.json stores endpoints, secret references and explicit authorized contact → participant mappings. No real messages are sent when configuring a channel. Set different server environment variables for provider API credentials and incoming webhook authentication.

Configure Evolution's incoming webhook as:

POST /v1/channels/whatsapp/{channelId}/webhook
x-factory-webhook-secret: <incoming webhook secret>

The parser and JID resolution are extracted directly from Estuda AI, with type erasure and source/shipped digests in runtime/engine/channels/estuda/source.json. The adapter handles phone alternates for opaque LIDs, rejects groups and unauthorized contacts, ignores outgoing messages, bounds body size and accepts text. Media needs a separately configured application adapter. The factory uses the Estuda InboundEnvelope/OutboundEnvelope vocabulary at this boundary without importing its learner database or domain permissions.

Message IDs suppress repeated model execution and delivery. Outbound dispatch intent is durable; provider uncertainty stays UNKNOWN and is not automatically resent. PROVIDER_ACCEPTED means acceptance, not delivery/read confirmation. humano, atendente, parar and stop enter sticky human handoff; the operator explicitly resumes automation. Contact authorization and webhook/provider references must be configured by the owning application. Web and WhatsApp sessions are separate unless the application implements authorized continuity.

Estuda AI validation

The opt-in createAgentFactoryProvider adapter in Estuda's tenant runtime uses the published HTTP contract through its existing LLMProvider port. Its real tutor and instructor use cases retain canonical context construction, local answer-disclosure guards, authorization and failure fallbacks. The bridge supports existing text agents; tool-based agents register their contracts in the factory instead of relaying model-supplied tool definitions. Bounded application context is explicit in the agent release and truncation is refused.

The adapter is exported by @estuda-ai/tenant-llm-runtime. Pass it through the use case's existing provider port with a server-side application credential and an authorized participant identifier. This is an explicit integration choice; installing the adapter does not change existing tenant routing.

runtime/node ../estuda-ai/node_modules/tsx/dist/cli.mjs scripts/prove-agent-factory-estuda.mts
runtime/node ../estuda-ai/node_modules/tsx/dist/cli.mjs scripts/prove-agent-factory-estuda.mts --live-model
runtime/node scripts/prove-agent-factory-browser.mjs
runtime/node --test tests/engine/factory.test.mjs

The live proof uses the available Ollama endpoint (OLLAMA_HOST) and FACTORY_LIVE_MODEL, defaulting to the locally installed qwen2.5:7b. All learner, teacher, schedule, contact and gameplay data are fictitious. The proof runs actual use cases, updates an agent without rebuilding Estuda, verifies rollback and independently exercises its actual disclosure guard. It changes no production routing and sends no real WhatsApp messages. These engineering results do not establish pedagogical efficacy, paying demand or a competitive moat.

Limitations

• Human usability is not yet measured. Automated journeys prove the path works; they do not prove ordinary developers find it easy. See the study protocol.
• Agent drafts, evaluations and releases live in the workspace's local agent store (.workstation/agent-factory, excluded from Git by default). Knowledge, profiles and tool contracts live in context-project.json. Releases move between machines as exported packages.
• Publishing an agent has no separate approver: the operator credential can publish to production once the production gates pass. Context Builds keep the Registry's separation of duties.
• Hosted-model keys must be environment variables of the agent service; there is no Keychain flow for model keys yet.
• OpenAPI and MCP imports are not implemented; capabilities are described in the guided form, as JSON Schema, or mapped to an existing HTTP endpoint.
• Knowledge accepts text formats only; convert PDFs and office files first.
• Cost is not measured unless pricing is configured; token counts are provider reported.

Delivery evidence

scripts/prove-agent-workspace.sh [--packaged] drives the real Workstation window through journeys A–F with a real local model (Ollama, qwen2.5:7b by default), a separately running synthetic application API (examples/agent-workspace/support-api.mjs), a separate application process (examples/agent-workspace/app.mjs) and the reference context project; it captures screenshots at 1512×982, 1280×720 and 1024×640 and checks for horizontal overflow. Results: evidence/agent-workspace-packaged/product-dogfood.json (packaged application) and evidence/agent-workspace/product-dogfood.json (development build). Engine tests (tests/engine/agent-workspace.test.mjs, tests/engine/api-adapter.test.mjs) and headless UI tests (tests/Workstation.Tests/AgentWorkspaceUiTests.cs) cover the same operations deterministically. Earlier browser, game, WhatsApp and Estuda receipts remain in evidence/factory-delivery.json.

The commercially testable offer is publish, integrate and improve an application's agents independently of the application release. Implementation and synthetic demonstrations do not prove faster integration, reduced release work or better task outcomes; a paid pilot must measure those. Billing, hosted tenant isolation and high-availability operation are outside this local/self-hosted release.