# 1. Install dependencies
npm install

# 2. Set up your API key
echo 'GOOGLE_API_KEY=your-key-here' > agent/.env

# 3. Start the app
npm run dev

├── src/
│   ├── app/
│   │   ├── page.tsx          # Main UI with CopilotKit integration
│   │   └── api/copilotkit/   # CopilotKit API route
│   ├── components/
│   │   ├── ArtifactPanel.tsx # Display generated artifacts
│   │   ├── ApiKeyInput.tsx   # Dynamic API key management
│   │   └── CustomChatInput.tsx
│   └── lib/
│       └── types.ts          # Shared TypeScript types
├── agent/
│   ├── agent.py              # LangGraph agent with tools
│   ├── server.py             # Custom routes (static files)
│   └── langgraph.json        # LangGraph configuration

// Frontend: src/app/page.tsx
const { state, setState } = useCoAgent<AgentState>({
  name: "sample_agent",
  initialState: { characters: [], backgrounds: [], scenes: [] },
});

// Update state from frontend
setState((prev) => ({ ...prev, apiKey: newKey }));

# Agent: agent/agent.py
class AgentState(MessagesState):
    characters: List[dict] = []
    backgrounds: List[dict] = []
    scenes: List[dict] = []
    apiKey: str = ""

# Read state in agent
api_key = state.get("apiKey", "")

// Frontend: Enable HITL for specific tool
useCopilotAction({
  name: "approve_image_prompt",
  disabled: true, // Agent calls this, not user
  handler: async ({ prompt }) => {
    // Show approval UI, return approved/rejected
  },
});

// Show real-time tool progress
useCopilotAction({
  name: "create_character",
  render: ({ status, result }) => (
    <ToolCard status={status} result={result} />
  ),
});

# agent/agent.py
@tool
async def create_character(
    name: str,
    description: str,
    prompt: str,
    state: Annotated[dict, InjectedState]  # Access shared state
) -> dict:
    api_key = state.get("apiKey", "")
    image_url = await generate_image(prompt, api_key=api_key)
    return {"name": name, "description": description, "imageUrl": image_url}

cd agent
railway link
railway up
railway variables --set "AGENT_URL=https://your-app.up.railway.app"
railway variables --set "GOOGLE_API_KEY=your-key"