inicialização do agente da uip

Sintaxe e opções para "uip agent init", que estrutura um novo projeto de agente de pouco código no disco.

uip agent init estrutura um novo projeto de agente de pouco código no disco. Quando executado dentro de um diretório de soluções, o projeto é registrado automaticamente no .uipx da solução ao redor. Ao executar fora de qualquer solução, um <name>Solution pai é estruturado automaticamente e o projeto do agente é aninhado dentro dele — passe --skip-solution-registration para desativar ambos os comportamentos e obter uma árvore de projeto vazia e não registrada.

Dois modos de estruturação estão disponíveis:

• Independente (padrão) — uma árvore de projeto de agente completa com agent.json, entry-points.json, project.uiproj, flow-layout.json, uma árvore evals/ (com um conjunto de avaliação padrão, avaliador semântico e avaliador de trajetória), mais features/ vazio e resources/ .
• Em linha no fluxo (--inline-in-flow) — um subdiretório nomeado por UUID dentro de um projeto de fluxo existente contendo agent.json e um flow-layout.json vazio, com pastas vazias evals/eval-sets/, features/ e resources/ . Nenhum entry-points.json ou project.uiproj, e nenhum registro automático de solução. O nó do agente embutido do fluxo deve fazer referência ao projectId gerado.

Resumo

uip agent init <path> [--conversational] [--model <model>] [--system-prompt <prompt>] [--force] [--skip-solution-registration] [--inline-in-flow]

Todas as invocações uip agent init honram as opções globais (--output, --output-filter, --log-level, --log-file). Os códigos de saída seguem o contrato padrão.

Argumentos

• <path> necessário) — Diretório de destino para o projeto do agente (relativo ou absoluto). O nome do diretório se torna o nome do agente no modo independente; ele deve corresponder [a-zA-Z0-9_ -]+. Quando --inline-in-flow é usado, <path> é o diretório do projeto de fluxo e um subdiretório nomeado pelo UUID é criado dentro dele.

Opções

Bandeira	Padrão	Finalidade
--conversational	desativada	Estruture um agente de conversa em vez de um autônomo.
--model <model>	sem padrão estático — escolhe um modelo recomendado para o tipo de agente autônomo/conversacional	Modelo de LLM a ser usado. Gravado em settings.model em agent.json.
--system-prompt <prompt>	—	Prompt inicial do sistema gravado messages[0] de agent.json. Importante apenas no modo autônomo.
--force	desativada	Substitui o diretório de destino mesmo se não estiver vazio. Apenas modo independente — o modo em linha sempre grava em uma pasta UUID nova.
--skip-solution-registration	desativada	Não registre automaticamente o projeto em uma solução adjacente e não crie automaticamente um <name>Solution pai.
--inline-in-flow	desativada	Estruture um agente em linha dentro de um projeto de fluxo. <path> argumento deve apontar para um diretório de projeto de fluxo existente (caso contrário, erro).

O modo independente se recusa a prosseguir se o diretório de destino existir e contiver algum arquivo, a menos que --force esteja definido.

Exemplos

# Simplest: scaffold an autonomous agent with the recommended default model
uip agent init ./my-agent --model gpt-5.4

# Scaffold a conversational agent
uip agent init ./my-agent --conversational --model anthropic.claude-sonnet-4-5-20250929-v1:0

# Scaffold outside any solution — a parent MyAgentSolution is auto-created
uip agent init ./my-agent

# Skip solution auto-registration entirely
uip agent init ./my-agent --skip-solution-registration

# Overwrite an existing non-empty directory
uip agent init ./my-agent --force

# Scaffold an inline agent inside an existing flow project
uip agent init ./my-flow --inline-in-flow

Formato dos dados (--output json)

Independente (Code: "AgentInit"):

{
  "Code": "AgentInit",
  "Data": {
    "Status": "Agent project created",
    "Path": "/abs/path/MyAgentSolution/my-agent",
    "Name": "my-agent",
    "Model": "gpt-5.4",
    "ProjectId": "a1b2c3d4-0000-0000-0000-000000000301",
    "NextSteps": "# Edit agent.json to configure prompts and resources\n...",
    "SolutionRegistration": {
      "Status": "Registered"
    },
    "AutoCreatedSolution": {
      "...": "present only when a parent solution was scaffolded automatically"
    },
    "ProjectArtifacts": {
      "...": "present only when the project was registered into a parent solution"
    }
  }
}

SolutionRegistration.Status está sempre presente — um destas opções: Registered, AlreadyRegistered, NotInSolution (nenhum pai .uipx encontrado e um novo não foi criado automaticamente) ou OptedOut (--skip-solution-registration foi aprovado) . AutoCreatedSolution está presente apenas quando um <Name>Solution pai foi estruturado para essa execução. ProjectArtifacts está presente apenas quando SolutionRegistration.Status é Registered ou AlreadyRegistered — ele espelha as entradas de recursos de artefatos que uip solution projects add produziria, portanto, uip solution pack não omite o projeto posteriormente.

Em linha (Code: "AgentInitInline"):

{
  "Code": "AgentInitInline",
  "Data": {
    "Status": "Inline agent created inside flow project",
    "Path": "/abs/path/my-flow/<uuid>",
    "ProjectId": "<uuid>",
    "Model": "gpt-5.4",
    "NextSteps": "# Edit agent.json to configure prompts and settings\n..."
  }
}

O modo incorporado nunca faz registro de solução — SolutionRegistration / AutoCreatedSolution / ProjectArtifacts nunca estão presentes nesta forma.

ProjectId é um UUID novo carimbos em agent.json e — no modo em linha — também é o nome da pasta. No modo independente, UUIDs adicionais são gerados para o ponto de entrada, o avaliador semântico, o avaliador de trajetória e o conjunto de avaliação padrão.

Arquivos gerados

Criações autônomas :

<path>/
  agent.json
  project.uiproj
  entry-points.json
  flow-layout.json
  evals/
    evaluators/
      <semantic-evaluator>.json
      <trajectory-evaluator>.json
    eval-sets/
      evaluation-set-default.json
  features/
  resources/

Inline-in-flow cria, dentro do projeto de fluxo:

<flow-path>/<new-uuid>/
  agent.json
  flow-layout.json           # empty ({})
  evals/eval-sets/
  features/
  resources/

Relacionado

• uip agent refresh — executado após cada edição para regenerar entry-points.json e bindings_v2.json.
• uip agent validate — verificação rigorosa de somente leitura antes do envio.
• uip solution projects add — vincule o agente com estrutura de dados a uma solução diferente daquela na qual ele foi registrado automaticamente.

Veja também

• Conceitos: habilidades — como os pontos de entrada de um agente aparecem como habilidades.
• Opções globais, Códigos de saída.