Skip to content

Authoring Agents

Cortex edits three kinds of resource, each with its own schema:

ResourceKindEditors
AgentAgentYAML editor and visual builder
RAG pipelineRAGPipelineYAML editor and visual builder
WorkflowWorkflowYAML editor

Everything is read from and saved to the active runtime (/v1/agents, /v1/rag/pipelines, /v1/workflows). Cortex keeps no local copy.

Monaco with validation, completion and hover against the agent schema. Errors show as you type, and saving sends the YAML to the runtime, which has the final word.

Snippets change with where the cursor is:

Cursor inOffered
An empty documentagent-skeleton (or the RAG or workflow skeleton, by file)
spec:identity, model, knowledge, prompts, orchestration, output_schema, chain, tools, prefetch, glyph-program, memory, guardrails, permissions, skills, a2a. Sections already present are not offered again. Every one validates against the schema
tools:tool-entry, tool-integration, tool-api, tool-mcp, tool-a2a
chain:chain-link, chain-link-default
guardrails:guardrail-rule

Helper opens a side panel with one card per section: what it is for, a snippet to copy or append, and its keys. A check marks the sections the agent already has; click one to jump to it.

Toolbar: Save, Deploy (see deploy targets), Pause, Test (opens the console on this agent), Helper, channel messages, Visual, Delete.

The agent sits at the centre of a canvas, and each spec section is a block around it. Drag a block from the palette to add the section; select one and press Delete to remove it.

BlockInspector
ModelThe default role and any named roles (planner, worker, reasoner, synthesizer, supervisor, stage:<name>…). Each role has a strategy and a ranked list of candidates: source (ollama, openai, openai_compat, azure_openai, litellm) and model, or a providerRef, plus endpoint, API key variable and temperature
PromptsThe system prompt
OrchestrationPattern (ReAct, Plan & Execute, Fan Out, Pipeline, Supervisor, Swarm, Glyph), iterations and timeout. Sub-agents for Fan Out and Pipeline. With Glyph, the program
ToolsThe seven tool types, below
KnowledgeThe RAG pipeline to query and top_k
PrefetchLookups run before the model (see below)
Memory, Guardrails, PermissionsBasic editors; see the caution below
A2APublishing over A2A in Nexus (spec.a2a.publicar), the card’s description (spec.identity.description) and spec.skills. Removing the block removes both sections. See A2A

Save writes the whole agent back to the runtime. Sections and keys the builder does not edit (identity, output_schema, chain, channels, a candidate’s contract…) are kept as they were.

The builder and the YAML editor are two views of the agent stored in the runtime, not a live mirror. After saving in one, reopen the other to see the change.

*.eval.yaml files (kind: Eval, run by astromesh-eval) are validated against their own schema: agent, thresholds.pass_rate, judge, cases or cases_file, with every case needing an expect or a rubric. The editor offers the eval-skeleton snippet.

Opening an agent in the visual builder upgrades two legacy formats and marks the tab as modified, so saving keeps the upgrade:

  • model.primary / fallback / routing become model.default with ranked candidates, and provider becomes source.
  • An inline type: rag tool becomes spec.knowledge. Its chunking and embedding settings belong to the RAG pipeline, so they are dropped from the agent.

The YAML editor shows the agent exactly as stored and migrates nothing.

TypeWhat it isEditor
builtinA runtime built-inPicked from the runtime’s list
agentAnother agent called as a toolPicked from the agent list; Cortex always sets agent:, which the runtime needs to load it
clientAnnounced to the model, executed by the callerName and description; parameters in YAML
integrationActions of a catalog integration through a tenant connectionSlug from the runtime’s catalog, connection, actions (writes are marked) and which writes need confirmation
apiA tenant’s own HTTP APIConnection, auth (header, bearer, basic, query) and operations: name, description, GET/POST, path, and whether it writes
mcpTools of a tenant’s MCP serverConnection, path, auth (bearer, header) and a snapshot of its tools with their input schema
a2aA remote agent that speaks A2A 1.0, through its Agent Card (core 0.74.0+)Card URL, credential by environment variable name (api_key_env or bearer_env), timeout, max bytes, accepted parts and the http opt-in for local development

For api and mcp, an operation or tool that writes is marked writes: true with mode: propose: the agent proposes the write and the run returns it as a proposal instead of executing it (see proposals).

The editors check the rules the runtime enforces when it loads the agent: kebab-case names (30 characters at most for MCP), snake_case operations, final tool names of 64 characters at most, at least one operation, no repeated operations, a description on every operation, paths starting with /, no headers in the request (auth goes in auth), MCP headers that are not reserved, and input_schema of type object.

If the runtime’s integration catalog is unavailable, the integration editor falls back to free text for slug, actions and connection.

A type: a2a tool is checked like the core checks it when it loads the agent: an https card URL (http only with Permitir http), a host and no credentials in the URL, exactly one credential variable with a valid name, timeout above 0 and at most 600 s, max_bytes from 1 byte to 16 MiB. Leave the description empty and the core builds it from the remote card. On the Nexus runtime pool only the environment variables the operator added exist, so a remote that needs a credential works from a standalone node. See A2A tools.

The A2A block publishes the agent itself: with publicar on, Nexus 0.27+ serves its Agent Card and JSON-RPC endpoint. The card’s description and skills come from this block. The block flags a skill the runtime would skip (a blank id, name or description) and repeated ids. Callers need the tenant’s API key, and an A2A turn never confirms a confirm-gated write.

spec.prefetch runs read-only lookups before the model is called and puts their results in the prompt. Each entry has a name, a tool (an integration action or an api read operation, suggested from the agent’s own tools), optional arguments (Jinja2) and an optional when condition. Only reads that are not in confirm are allowed; the runtime rejects the rest at load time.

With the glyph pattern, the agent can carry a fixed program in spec.program, edited from the Orchestration inspector. A program on any other pattern stops the runtime from loading the agent, so the inspector warns and offers to delete it. See Glyph.

FromWhat you get
Blank AgentName, display name, description, model source and model. Creates a ReAct agent with one default candidate and opens it in YAML
From Template…The runtime’s templates, searchable and filtered by category. Fill in the template’s variables and Cortex creates the agent (not deployed) and opens it

RAG Pipelines → New Pipeline asks for a name, a vector store (pgvector, qdrant, chroma, faiss) and an embeddings provider (ollama, hf, sentence_transformer), and opens the pipeline in the visual builder. Its blocks are Chunking, Embeddings, Vector Store, Reranking and Retrieval. Agents use a pipeline through spec.knowledge.

Workflows → New Workflow opens a *.workflow.yaml editor with a three-step skeleton: an agent step, an approval step and a tool step.

  • Run runs the workflow named in metadata.name.
  • Register blueprint registers the workflow on the runtime. The agents and pipelines it references must already exist there.

Runs and approvals are covered in Console & Traces.

Built by FAiNANSU